Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Improve SensorManager documentation" into gingerbread

Browse Source
This commit is contained in:
Mathias Agopian
2010-06-21 15:10:13 -07:00
committed by Android (Google) Code Review
parent 7fbdc84e87 74cde2cee9
commit 7e73a2ce17
3 changed files with 540 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
core/java/android/hardware/Sensor.java
View File

@@ -17,65 +17,61 @@
package android.hardware; package android.hardware;
/** /**
* Class representing a sensor. Use {@link SensorManager#getSensorList} * Class representing a sensor. Use {@link SensorManager#getSensorList} to get
* to get the list of available Sensors. * the list of available Sensors.
*/ */
public class Sensor { public class Sensor {
/** /**
* A constant describing an accelerometer sensor type. * A constant describing an accelerometer sensor type. See
* See {@link android.hardware.SensorEvent SensorEvent} * {@link android.hardware.SensorEvent SensorEvent} for more details.
* for more details.
*/ */
public static final int TYPE_ACCELEROMETER = 1; public static final int TYPE_ACCELEROMETER = 1;
/** /**
* A constant describing a magnetic field sensor type. * A constant describing a magnetic field sensor type. See
* See {@link android.hardware.SensorEvent SensorEvent} * {@link android.hardware.SensorEvent SensorEvent} for more details.
* for more details.
*/ */
public static final int TYPE_MAGNETIC_FIELD = 2; public static final int TYPE_MAGNETIC_FIELD = 2;
/** /**
* A constant describing an orientation sensor type. * A constant describing an orientation sensor type. See
* See {@link android.hardware.SensorEvent SensorEvent} * {@link android.hardware.SensorEvent SensorEvent} for more details.
* for more details. *
* @deprecated use {@link android.hardware.SensorManager#getOrientation * @deprecated use {@link android.hardware.SensorManager#getOrientation
* SensorManager.getOrientation()} instead. * SensorManager.getOrientation()} instead.
*/ */
@Deprecated @Deprecated
public static final int TYPE_ORIENTATION = 3; public static final int TYPE_ORIENTATION = 3;
/** A constant describing a gyroscope sensor type */ /** A constant describing a gyroscope sensor type */
public static final int TYPE_GYROSCOPE = 4; public static final int TYPE_GYROSCOPE = 4;
/** /**
* A constant describing an light sensor type. * A constant describing an light sensor type. See
* See {@link android.hardware.SensorEvent SensorEvent} * {@link android.hardware.SensorEvent SensorEvent} for more details.
* for more details.
*/ */
public static final int TYPE_LIGHT = 5; public static final int TYPE_LIGHT = 5;
/** A constant describing a pressure sensor type */ /** A constant describing a pressure sensor type */
public static final int TYPE_PRESSURE = 6; public static final int TYPE_PRESSURE = 6;
/** A constant describing a temperature sensor type */ /** A constant describing a temperature sensor type */
public static final int TYPE_TEMPERATURE = 7; public static final int TYPE_TEMPERATURE = 7;
/** /**
* A constant describing an proximity sensor type. * A constant describing an proximity sensor type. See
* See {@link android.hardware.SensorEvent SensorEvent} * {@link android.hardware.SensorEvent SensorEvent} for more details.
* for more details.
*/ */
public static final int TYPE_PROXIMITY = 8; public static final int TYPE_PROXIMITY = 8;
/**
/**
* A constant describing all sensor types. * A constant describing all sensor types.
*/ */
public static final int TYPE_ALL = -1; public static final int TYPE_ALL = -1;
/* Some of these fields are set only by the native bindings in /* Some of these fields are set only by the native bindings in
* SensorManager. * SensorManager.
*/ */
private String mName; private String mName;
@@ -87,8 +83,8 @@ public class Sensor {
private float mResolution; private float mResolution;
private float mPower; private float mPower;
private int mLegacyType; private int mLegacyType;
Sensor() { Sensor() {
} }
@@ -105,51 +101,51 @@ public class Sensor {
public String getVendor() { public String getVendor() {
return mVendor; return mVendor;
} }
/** /**
* @return generic type of this sensor. * @return generic type of this sensor.
*/ */
public int getType() { public int getType() {
return mType; return mType;
} }
/** /**
* @return version of the sensor's module. * @return version of the sensor's module.
*/ */
public int getVersion() { public int getVersion() {
return mVersion; return mVersion;
} }
/** /**
* @return maximum range of the sensor in the sensor's unit. * @return maximum range of the sensor in the sensor's unit.
*/ */
public float getMaximumRange() { public float getMaximumRange() {
return mMaxRange; return mMaxRange;
} }
/** /**
* @return resolution of the sensor in the sensor's unit. * @return resolution of the sensor in the sensor's unit.
*/ */
public float getResolution() { public float getResolution() {
return mResolution; return mResolution;
} }
/** /**
* @return the power in mA used by this sensor while in use * @return the power in mA used by this sensor while in use
*/ */
public float getPower() { public float getPower() {
return mPower; return mPower;
} }
int getHandle() { int getHandle() {
return mHandle; return mHandle;
} }
void setRange(float max, float res) { void setRange(float max, float res) {
mMaxRange = max; mMaxRange = max;
mResolution = res; mResolution = res;
} }
void setLegacyType(int legacyType) { void setLegacyType(int legacyType) {
mLegacyType = legacyType; mLegacyType = legacyType;
} }

209
core/java/android/hardware/SensorEvent.java
View File

@@ -17,26 +17,36 @@
package android.hardware; package android.hardware;
/** /**
* This class represents a sensor event and holds informations such as the * <p>
* sensor type (eg: accelerometer, orientation, etc...), the time-stamp, * This class represents a {@link android.hardware.Sensor Sensor} event and
* accuracy and of course the sensor's {@link SensorEvent#values data}. * holds informations such as the sensor's type, the time-stamp, accuracy and of
* course the sensor's {@link SensorEvent#values data}.
* </p>
* *
* <p><u>Definition of the coordinate system used by the SensorEvent API.</u><p> * <p>
* * <u>Definition of the coordinate system used by the SensorEvent API.</u>
* <pre> * </p>
* The coordinate space is defined relative to the screen of the phone *
* in its default orientation. The axes are not swapped when the device's * <p>
* screen orientation changes. * The coordinate space is defined relative to the screen of the phone in its
* * default orientation. The axes are not swapped when the device's screen
* The OpenGL ES coordinate system is used. The origin is in the * orientation changes.
* lower-left corner with respect to the screen, with the X axis horizontal * </p>
* 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 * <p>
* behind the screen have negative Z values. * 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.
* </p>
*
* <p>
* <b>Note:</b> This coordinate system is different from the one used in the * <b>Note:</b> This coordinate system is different from the one used in the
* Android 2D APIs where the origin is in the top-left corner. * Android 2D APIs where the origin is in the top-left corner.
* </p>
* *
* <pre>
* x<0 x>0 * x<0 x>0
* ^ * ^
* | * |
@@ -60,100 +70,125 @@ package android.hardware;
public class SensorEvent { public class SensorEvent {
/** /**
* <p>
* The length and contents of the values array vary depending on which * The length and contents of the values array vary depending on which
* sensor type is being monitored (see also {@link SensorEvent} for a * {@link android.hardware.Sensor sensor} type is being monitored (see also
* definition of the coordinate system used): * {@link SensorEvent} for a definition of the coordinate system used):
* * </p>
* <p>{@link android.hardware.Sensor#TYPE_ORIENTATION Sensor.TYPE_ORIENTATION}:<p>
* All values are angles in degrees.
*
* <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>values[1]: Pitch, rotation around X axis (-180 to 180), * <h3>{@link android.hardware.Sensor#TYPE_ORIENTATION
* with positive values when the z-axis moves <b>toward</b> the y-axis. * Sensor.TYPE_ORIENTATION}:</h3> All values are angles in degrees.
* *
* <p>values[2]: Roll, rotation around Y axis (-90 to 90), with * <ul>
* positive values when the x-axis moves <b>toward</b> the z-axis. * <p>
* * values[0]: Azimuth, angle between the magnetic north direction and the Y
* <p><b>Important note:</b> For historical reasons the roll angle is * axis, around the Z axis (0 to 359). 0=North, 90=East, 180=South, 270=West
* positive in the clockwise direction (mathematically speaking, it
* should be positive in the counter-clockwise direction).
* *
* <p><b>Note:</b> This definition is different from <b>yaw, pitch and * <p>
* roll</b> used in aviation where the X axis is along the long side of * values[1]: Pitch, rotation around X axis (-180 to 180), with positive
* the plane (tail to nose). * values when the z-axis moves <b>toward</b> the y-axis.
* *
* <p><b>Note:</b> This sensor type exists for legacy reasons, please use * <p>
* {@link android.hardware.SensorManager#getRotationMatrix * values[2]: Roll, rotation around Y axis (-90 to 90), with positive values
* getRotationMatrix()} in conjunction with * when the x-axis moves <b>toward</b> the z-axis.
* {@link android.hardware.SensorManager#remapCoordinateSystem * </ul>
* remapCoordinateSystem()} and
* {@link android.hardware.SensorManager#getOrientation getOrientation()}
* to compute these values instead.
* *
* <p>{@link android.hardware.Sensor#TYPE_ACCELEROMETER Sensor.TYPE_ACCELEROMETER}:<p> * <p>
* All values are in SI units (m/s^2) and measure the acceleration applied * <b>Important note:</b> For historical reasons the roll angle is positive
* to the phone minus the force of gravity. * in the clockwise direction (mathematically speaking, it should be
* * positive in the counter-clockwise direction).
* <p>values[0]: Acceleration minus Gx on the x-axis
* <p>values[1]: Acceleration minus Gy on the y-axis
* <p>values[2]: Acceleration minus Gz on the z-axis
*
* <p><u>Examples</u>:
* <li>When the device lies flat on a table and is pushed on its left
* side toward the right, the x acceleration value is positive.</li>
*
* <li>When the device lies flat on a table, the acceleration value is
* +9.81, which correspond to the acceleration of the device (0 m/s^2)
* minus the force of gravity (-9.81 m/s^2).</li>
*
* <li>When the device lies flat on a table and is pushed toward the sky
* with an acceleration of A m/s^2, the acceleration value is equal to
* A+9.81 which correspond to the acceleration of the
* device (+A m/s^2) minus the force of gravity (-9.81 m/s^2).</li>
*
*
* <p>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD Sensor.TYPE_MAGNETIC_FIELD}:<p>
* All values are in micro-Tesla (uT) and measure the ambient magnetic
* field in the X, Y and Z axis.
* *
* <p>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:<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).
* *
* <p>values[0]: Ambient light level in SI lux units * <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>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:<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.
* *
* <p>values[0]: Proximity sensor distance measured in centimeters * <ul>
* <p>
* values[0]: Acceleration minus Gx on the x-axis
* <p>
* values[1]: Acceleration minus Gy on the y-axis
* <p>
* values[2]: Acceleration minus Gz on the z-axis
* </ul>
* *
* <p> Note that some proximity sensors only support a binary "close" or "far" measurement. * <p>
* In this case, the sensor should report its maxRange value in the "far" state and a value * <u>Examples</u>:
* less than maxRange in the "near" state. * <ul>
* <li>When the device lies flat on a table and is pushed on its left side
* toward the right, the x acceleration value is positive.</li>
*
* <li>When the device lies flat on a table, the acceleration value is
* +9.81, which correspond to the acceleration of the device (0 m/s^2) minus
* the force of gravity (-9.81 m/s^2).</li>
*
* <li>When the device lies flat on a table and is pushed toward the sky
* with an acceleration of A m/s^2, the acceleration value is equal to
* A+9.81 which correspond to the acceleration of the device (+A m/s^2)
* minus the force of gravity (-9.81 m/s^2).</li>
* </ul>
*
*
* <h3>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
* Sensor.TYPE_MAGNETIC_FIELD}:</h3>
* 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>
*
* <ul>
* <p>
* values[0]: Ambient light level in SI lux units
* </ul>
*
* <h3>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:
* </h3>
*
* <ul>
* <p>
* values[0]: Proximity sensor distance measured in centimeters
* </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.
*/ */
public final float[] values; public final float[] values;
/** /**
* The sensor that generated this event. * The sensor that generated this event. See
* See {@link android.hardware.SensorManager SensorManager} * {@link android.hardware.SensorManager SensorManager} for details.
* for details.
*/ */
public Sensor sensor; public Sensor sensor;
/** /**
* The accuracy of this event. * The accuracy of this event. See {@link android.hardware.SensorManager
* See {@link android.hardware.SensorManager SensorManager} * SensorManager} for details.
* for details.
*/ */
public int accuracy; public int accuracy;
/** /**
* The time in nanosecond at which the event happened * The time in nanosecond at which the event happened
*/ */
public long timestamp; public long timestamp;
SensorEvent(int size) { SensorEvent(int size) {
values = new float[size]; values = new float[size];
} }

596
core/java/android/hardware/SensorManager.java
View File

@@ -41,9 +41,11 @@ import java.util.HashMap;
import java.util.List; import java.util.List;
/** /**
* Class that lets you access the device's sensors. Get an instance of this * SensorManager lets you access the device's {@link android.hardware.Sensor
* class by calling {@link android.content.Context#getSystemService(java.lang.String) * sensors}. Get an instance of this class by calling
* Context.getSystemService()} with an argument of {@link android.content.Context#SENSOR_SERVICE}. * {@link android.content.Context#getSystemService(java.lang.String)
* Context.getSystemService()} with the argument
* {@link android.content.Context#SENSOR_SERVICE}.
*/ */
public class SensorManager public class SensorManager
{ {
@@ -53,172 +55,220 @@ public class SensorManager
/* NOTE: sensor IDs must be a power of 2 */ /* NOTE: sensor IDs must be a power of 2 */
/** /**
* A constant describing an orientation sensor. * A constant describing an orientation sensor. See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_ORIENTATION = 1 << 0; public static final int SENSOR_ORIENTATION = 1 << 0;
/** /**
* A constant describing an accelerometer. * A constant describing an accelerometer. See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_ACCELEROMETER = 1 << 1; public static final int SENSOR_ACCELEROMETER = 1 << 1;
/** /**
* A constant describing a temperature sensor * A constant describing a temperature sensor See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_TEMPERATURE = 1 << 2; public static final int SENSOR_TEMPERATURE = 1 << 2;
/** /**
* A constant describing a magnetic sensor * A constant describing a magnetic sensor See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_MAGNETIC_FIELD = 1 << 3; public static final int SENSOR_MAGNETIC_FIELD = 1 << 3;
/** /**
* A constant describing an ambient light sensor * A constant describing an ambient light sensor See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_LIGHT = 1 << 4; public static final int SENSOR_LIGHT = 1 << 4;
/** /**
* A constant describing a proximity sensor * A constant describing a proximity sensor See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_PROXIMITY = 1 << 5; public static final int SENSOR_PROXIMITY = 1 << 5;
/** /**
* A constant describing a Tricorder * A constant describing a Tricorder See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_TRICORDER = 1 << 6; public static final int SENSOR_TRICORDER = 1 << 6;
/** /**
* A constant describing an orientation sensor. * A constant describing an orientation sensor. See
* See {@link android.hardware.SensorListener SensorListener} for more details. * {@link android.hardware.SensorListener SensorListener} for more details.
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_ORIENTATION_RAW = 1 << 7; public static final int SENSOR_ORIENTATION_RAW = 1 << 7;
/** A constant that includes all sensors /**
* A constant that includes all sensors
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_ALL = 0x7F; public static final int SENSOR_ALL = 0x7F;
/** Smallest sensor ID /**
* Smallest sensor ID
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_MIN = SENSOR_ORIENTATION; public static final int SENSOR_MIN = SENSOR_ORIENTATION;
/** Largest sensor ID /**
* Largest sensor ID
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int SENSOR_MAX = ((SENSOR_ALL + 1)>>1); public static final int SENSOR_MAX = ((SENSOR_ALL + 1)>>1);
/** Index of the X value in the array returned by /**
* Index of the X value in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int DATA_X = 0; public static final int DATA_X = 0;
/** Index of the Y value in the array returned by
/**
* Index of the Y value in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int DATA_Y = 1; public static final int DATA_Y = 1;
/** Index of the Z value in the array returned by
/**
* Index of the Z value in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int DATA_Z = 2; public static final int DATA_Z = 2;
/** Offset to the untransformed values in the array returned by /**
* Offset to the untransformed values in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int RAW_DATA_INDEX = 3; public static final int RAW_DATA_INDEX = 3;
/** Index of the untransformed X value in the array returned by /**
* Index of the untransformed X value in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int RAW_DATA_X = 3; public static final int RAW_DATA_X = 3;
/** Index of the untransformed Y value in the array returned by
/**
* Index of the untransformed Y value in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int RAW_DATA_Y = 4; public static final int RAW_DATA_Y = 4;
/** Index of the untransformed Z value in the array returned by
/**
* Index of the untransformed Z value in the array returned by
* {@link android.hardware.SensorListener#onSensorChanged} * {@link android.hardware.SensorListener#onSensorChanged}
*
* @deprecated use {@link android.hardware.Sensor Sensor} instead. * @deprecated use {@link android.hardware.Sensor Sensor} instead.
*/ */
@Deprecated @Deprecated
public static final int RAW_DATA_Z = 5; public static final int RAW_DATA_Z = 5;
/** Standard gravity (g) on Earth. This value is equivalent to 1G */ /** Standard gravity (g) on Earth. This value is equivalent to 1G */
public static final float STANDARD_GRAVITY = 9.80665f; public static final float STANDARD_GRAVITY = 9.80665f;
/** values returned by the accelerometer in various locations in the universe. /** Sun's gravity in SI units (m/s^2) */
* all values are in SI units (m/s^2) */
public static final float GRAVITY_SUN = 275.0f; public static final float GRAVITY_SUN = 275.0f;
/** Mercury's gravity in SI units (m/s^2) */
public static final float GRAVITY_MERCURY = 3.70f; public static final float GRAVITY_MERCURY = 3.70f;
/** Venus' gravity in SI units (m/s^2) */
public static final float GRAVITY_VENUS = 8.87f; public static final float GRAVITY_VENUS = 8.87f;
/** Earth's gravity in SI units (m/s^2) */
public static final float GRAVITY_EARTH = 9.80665f; public static final float GRAVITY_EARTH = 9.80665f;
/** The Moon's gravity in SI units (m/s^2) */
public static final float GRAVITY_MOON = 1.6f; public static final float GRAVITY_MOON = 1.6f;
/** Mars' gravity in SI units (m/s^2) */
public static final float GRAVITY_MARS = 3.71f; public static final float GRAVITY_MARS = 3.71f;
/** Jupiter's gravity in SI units (m/s^2) */
public static final float GRAVITY_JUPITER = 23.12f; public static final float GRAVITY_JUPITER = 23.12f;
/** Saturn's gravity in SI units (m/s^2) */
public static final float GRAVITY_SATURN = 8.96f; public static final float GRAVITY_SATURN = 8.96f;
/** Uranus' gravity in SI units (m/s^2) */
public static final float GRAVITY_URANUS = 8.69f; public static final float GRAVITY_URANUS = 8.69f;
/** Neptune's gravity in SI units (m/s^2) */
public static final float GRAVITY_NEPTUNE = 11.0f; public static final float GRAVITY_NEPTUNE = 11.0f;
/** Pluto's gravity in SI units (m/s^2) */
public static final float GRAVITY_PLUTO = 0.6f; public static final float GRAVITY_PLUTO = 0.6f;
/** Gravity (estimate) on the first Death Star in Empire units (m/s^2) */
public static final float GRAVITY_DEATH_STAR_I = 0.000000353036145f; public static final float GRAVITY_DEATH_STAR_I = 0.000000353036145f;
/** Gravity on the island */
public static final float GRAVITY_THE_ISLAND = 4.815162342f; public static final float GRAVITY_THE_ISLAND = 4.815162342f;
/** Maximum magnetic field on Earth's surface */ /** Maximum magnetic field on Earth's surface */
public static final float MAGNETIC_FIELD_EARTH_MAX = 60.0f; public static final float MAGNETIC_FIELD_EARTH_MAX = 60.0f;
/** Minimum magnetic field on Earth's surface */ /** Minimum magnetic field on Earth's surface */
public static final float MAGNETIC_FIELD_EARTH_MIN = 30.0f; public static final float MAGNETIC_FIELD_EARTH_MIN = 30.0f;
/** Various luminance values during the day (lux) */ /** Maximum luminance of sunlight in lux */
public static final float LIGHT_SUNLIGHT_MAX = 120000.0f; public static final float LIGHT_SUNLIGHT_MAX = 120000.0f;
/** luminance of sunlight in lux */
public static final float LIGHT_SUNLIGHT = 110000.0f; public static final float LIGHT_SUNLIGHT = 110000.0f;
/** luminance in shade in lux */
public static final float LIGHT_SHADE = 20000.0f; public static final float LIGHT_SHADE = 20000.0f;
/** luminance under an overcast sky in lux */
public static final float LIGHT_OVERCAST = 10000.0f; public static final float LIGHT_OVERCAST = 10000.0f;
/** luminance at sunrise in lux */
public static final float LIGHT_SUNRISE = 400.0f; public static final float LIGHT_SUNRISE = 400.0f;
/** luminance under a cloudy sky in lux */
public static final float LIGHT_CLOUDY = 100.0f; public static final float LIGHT_CLOUDY = 100.0f;
/** Various luminance values during the night (lux) */ /** luminance at night with full moon in lux */
public static final float LIGHT_FULLMOON = 0.25f; public static final float LIGHT_FULLMOON = 0.25f;
/** luminance at night with no moon in lux*/
public static final float LIGHT_NO_MOON = 0.001f; public static final float LIGHT_NO_MOON = 0.001f;
/** get sensor data as fast as possible */ /** get sensor data as fast as possible */
public static final int SENSOR_DELAY_FASTEST = 0; public static final int SENSOR_DELAY_FASTEST = 0;
/** rate suitable for games */ /** rate suitable for games */
@@ -229,16 +279,22 @@ public class SensorManager
public static final int SENSOR_DELAY_NORMAL = 3; public static final int SENSOR_DELAY_NORMAL = 3;
/** The values returned by this sensor cannot be trusted, calibration /**
* is needed or the environment doesn't allow readings */ * The values returned by this sensor cannot be trusted, calibration is
* needed or the environment doesn't allow readings
*/
public static final int SENSOR_STATUS_UNRELIABLE = 0; public static final int SENSOR_STATUS_UNRELIABLE = 0;
/** This sensor is reporting data with low accuracy, calibration with the /**
* environment is needed */ * This sensor is reporting data with low accuracy, calibration with the
* environment is needed
*/
public static final int SENSOR_STATUS_ACCURACY_LOW = 1; public static final int SENSOR_STATUS_ACCURACY_LOW = 1;
/** This sensor is reporting data with an average level of accuracy, /**
* calibration with the environment may improve the readings */ * This sensor is reporting data with an average level of accuracy,
* calibration with the environment may improve the readings
*/
public static final int SENSOR_STATUS_ACCURACY_MEDIUM = 2; public static final int SENSOR_STATUS_ACCURACY_MEDIUM = 2;
/** This sensor is reporting data with maximum accuracy */ /** This sensor is reporting data with maximum accuracy */
@@ -586,9 +642,10 @@ public class SensorManager
return 0; return 0;
} }
/** @return available sensors. /**
* @return available sensors.
* @deprecated This method is deprecated, use * @deprecated This method is deprecated, use
* {@link SensorManager#getSensorList(int)} instead * {@link SensorManager#getSensorList(int)} instead
*/ */
@Deprecated @Deprecated
public int getSensors() { public int getSensors() {
@@ -612,12 +669,14 @@ public class SensorManager
} }
/** /**
* Use this method to get the list of available sensors of a certain * Use this method to get the list of available sensors of a certain type.
* type. Make multiple calls to get sensors of different types or use * Make multiple calls to get sensors of different types or use
* {@link android.hardware.Sensor#TYPE_ALL Sensor.TYPE_ALL} to get all * {@link android.hardware.Sensor#TYPE_ALL Sensor.TYPE_ALL} to get all the
* the sensors. * sensors.
* *
* @param type of sensors requested * @param type
* of sensors requested
*
* @return a list of sensors matching the asked type. * @return a list of sensors matching the asked type.
*/ */
public List<Sensor> getSensorList(int type) { public List<Sensor> getSensorList(int type) {
@@ -644,13 +703,14 @@ public class SensorManager
} }
/** /**
* Use this method to get the default sensor for a given type. Note that * Use this method to get the default sensor for a given type. Note that the
* the returned sensor could be a composite sensor, and its data could be * returned sensor could be a composite sensor, and its data could be
* averaged or filtered. If you need to access the raw sensors use * averaged or filtered. If you need to access the raw sensors use
* {@link SensorManager#getSensorList(int) getSensorList}. * {@link SensorManager#getSensorList(int) getSensorList}.
* *
* * @param type
* @param type of sensors requested * of sensors requested
*
* @return the default sensors matching the asked type. * @return the default sensors matching the asked type.
*/ */
public Sensor getDefaultSensor(int type) { public Sensor getDefaultSensor(int type) {
@@ -659,17 +719,21 @@ public class SensorManager
return l.isEmpty() ? null : l.get(0); return l.isEmpty() ? null : l.get(0);
} }
/** /**
* Registers a listener for given sensors. * Registers a listener for given sensors.
*
* @deprecated This method is deprecated, use * @deprecated This method is deprecated, use
* {@link SensorManager#registerListener(SensorEventListener, Sensor, int)} * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)}
* instead. * instead.
* *
* @param listener sensor listener object * @param listener
* @param sensors a bit masks of the sensors to register to * sensor listener object
* *
* @return true if the sensor is supported and successfully enabled * @param sensors
* a bit masks of the sensors to register to
*
* @return <code>true</code> if the sensor is supported and successfully
* enabled
*/ */
@Deprecated @Deprecated
public boolean registerListener(SensorListener listener, int sensors) { public boolean registerListener(SensorListener listener, int sensors) {
@@ -678,18 +742,26 @@ public class SensorManager
/** /**
* Registers a SensorListener for given sensors. * Registers a SensorListener for given sensors.
*
* @deprecated This method is deprecated, use * @deprecated This method is deprecated, use
* {@link SensorManager#registerListener(SensorEventListener, Sensor, int)} * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)}
* instead. * instead.
* *
* @param listener sensor listener object * @param listener
* @param sensors a bit masks of the sensors to register to * sensor listener object
* @param rate rate of events. This is only a hint to the system. events *
* may be received faster or slower than the specified rate. Usually events * @param sensors
* are received faster. The value must be one of {@link #SENSOR_DELAY_NORMAL}, * a bit masks of the sensors to register to
* {@link #SENSOR_DELAY_UI}, {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}. *
* * @param rate
* @return true if the sensor is supported and successfully enabled * rate of events. This is only a hint to the system. events may be
* received faster or slower than the specified rate. Usually events
* are received faster. The value must be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}.
*
* @return <code>true</code> if the sensor is supported and successfully
* enabled
*/ */
@Deprecated @Deprecated
public boolean registerListener(SensorListener listener, int sensors, int rate) { public boolean registerListener(SensorListener listener, int sensors, int rate) {
@@ -747,12 +819,16 @@ public class SensorManager
/** /**
* Unregisters a listener for the sensors with which it is registered. * Unregisters a listener for the sensors with which it is registered.
*
* @deprecated This method is deprecated, use * @deprecated This method is deprecated, use
* {@link SensorManager#unregisterListener(SensorEventListener, Sensor)} * {@link SensorManager#unregisterListener(SensorEventListener, Sensor)}
* instead. * instead.
* *
* @param listener a SensorListener object * @param listener
* @param sensors a bit masks of the sensors to unregister from * a SensorListener object
*
* @param sensors
* a bit masks of the sensors to unregister from
*/ */
@Deprecated @Deprecated
public void unregisterListener(SensorListener listener, int sensors) { public void unregisterListener(SensorListener listener, int sensors) {
@@ -815,11 +891,13 @@ public class SensorManager
/** /**
* Unregisters a listener for all sensors. * Unregisters a listener for all sensors.
*
* @deprecated This method is deprecated, use * @deprecated This method is deprecated, use
* {@link SensorManager#unregisterListener(SensorEventListener)} * {@link SensorManager#unregisterListener(SensorEventListener)}
* instead. * instead.
* *
* @param listener a SensorListener object * @param listener
* a SensorListener object
*/ */
@Deprecated @Deprecated
public void unregisterListener(SensorListener listener) { public void unregisterListener(SensorListener listener) {
@@ -828,10 +906,12 @@ public class SensorManager
/** /**
* Unregisters a listener for the sensors with which it is registered. * Unregisters a listener for the sensors with which it is registered.
* *
* @param listener a SensorEventListener object * @param listener
* @param sensor the sensor to unregister from * a SensorEventListener object
* * @param sensor
* the sensor to unregister from
*
*/ */
public void unregisterListener(SensorEventListener listener, Sensor sensor) { public void unregisterListener(SensorEventListener listener, Sensor sensor) {
unregisterListener((Object)listener, sensor); unregisterListener((Object)listener, sensor);
@@ -839,50 +919,68 @@ public class SensorManager
/** /**
* Unregisters a listener for all sensors. * Unregisters a listener for all sensors.
* *
* @param listener a SensorListener object * @param listener
* * a SensorListener object
*
*/ */
public void unregisterListener(SensorEventListener listener) { public void unregisterListener(SensorEventListener listener) {
unregisterListener((Object)listener); unregisterListener((Object)listener);
} }
/** /**
* Registers a {@link android.hardware.SensorEventListener SensorEventListener} * Registers a {@link android.hardware.SensorEventListener
* for the given sensor. * SensorEventListener} for the given sensor.
* *
* @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object. * @param listener
* @param sensor The {@link android.hardware.Sensor Sensor} to register to. * A {@link android.hardware.SensorEventListener SensorEventListener}
* @param rate The rate {@link android.hardware.SensorEvent sensor events} are delivered at. * object.
* This is only a hint to the system. Events may be received faster or *
* slower than the specified rate. Usually events are received faster. The value must be * @param sensor
* one of {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI}, {@link #SENSOR_DELAY_GAME}, * The {@link android.hardware.Sensor Sensor} to register to.
* or {@link #SENSOR_DELAY_FASTEST}. *
* * @param rate
* @return true if the sensor is supported and successfully enabled. * The rate {@link android.hardware.SensorEvent sensor events} are
* * delivered at. This is only a hint to the system. Events may be
* received faster or slower than the specified rate. Usually events
* are received faster. The value must be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}.
*
* @return <code>true</code> if the sensor is supported and successfully
* enabled.
*
*/ */
public boolean registerListener(SensorEventListener listener, Sensor sensor, int rate) { public boolean registerListener(SensorEventListener listener, Sensor sensor, int rate) {
return registerListener(listener, sensor, rate, null); return registerListener(listener, sensor, rate, null);
} }
/** /**
* Registers a {@link android.hardware.SensorEventListener SensorEventListener} * Registers a {@link android.hardware.SensorEventListener
* for the given sensor. * SensorEventListener} for the given sensor.
* *
* @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object. * @param listener
* @param sensor The {@link android.hardware.Sensor Sensor} to register to. * A {@link android.hardware.SensorEventListener SensorEventListener}
* @param rate The rate {@link android.hardware.SensorEvent sensor events} are delivered at. * object.
* This is only a hint to the system. Events may be received faster or *
* slower than the specified rate. Usually events are received faster. The value must be one * @param sensor
* of {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI}, {@link #SENSOR_DELAY_GAME}, or * The {@link android.hardware.Sensor Sensor} to register to.
* {@link #SENSOR_DELAY_FASTEST}. *
* @param handler The {@link android.os.Handler Handler} the * @param rate
* {@link android.hardware.SensorEvent sensor events} will be delivered to. * The rate {@link android.hardware.SensorEvent sensor events} are
* * delivered at. This is only a hint to the system. Events may be
* received faster or slower than the specified rate. Usually events
* are received faster. The value must be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}.
*
* @param handler
* The {@link android.os.Handler Handler} the
* {@link android.hardware.SensorEvent sensor events} will be
* delivered to.
*
* @return true if the sensor is supported and successfully enabled. * @return true if the sensor is supported and successfully enabled.
* *
*/ */
public boolean registerListener(SensorEventListener listener, Sensor sensor, int rate, public boolean registerListener(SensorEventListener listener, Sensor sensor, int rate,
Handler handler) { Handler handler) {
@@ -1003,95 +1101,126 @@ public class SensorManager
} }
/** /**
* Computes the inclination matrix <b>I</b> as well as the rotation * <p>
* matrix <b>R</b> transforming a vector from the * Computes the inclination matrix <b>I</b> as well as the rotation matrix
* device coordinate system to the world's coordinate system which is * <b>R</b> transforming a vector from the device coordinate system to the
* defined as a direct orthonormal basis, where: * world's coordinate system which is defined as a direct orthonormal basis,
* where:
* </p>
* *
* <ul>
* <li>X is defined as the vector product <b>Y.Z</b> (It is tangential to * <li>X is defined as the vector product <b>Y.Z</b> (It is tangential to
* the ground at the device's current location and roughly points East).</li> * the ground at the device's current location and roughly points East).</li>
* <li>Y is tangential to the ground at the device's current location and * <li>Y is tangential to the ground at the device's current location and
* points towards the magnetic North Pole.</li> * points towards the magnetic North Pole.</li>
* <li>Z points towards the sky and is perpendicular to the ground.</li> * <li>Z points towards the sky and is perpendicular to the ground.</li>
* </ul>
* <p> * <p>
* <hr> * <hr>
* <p>By definition: * <p>
* <p>[0 0 g] = <b>R</b> * <b>gravity</b> (g = magnitude of gravity) * By definition:
* <p>[0 m 0] = <b>I</b> * <b>R</b> * <b>geomagnetic</b> * <p>
* (m = magnitude of geomagnetic field) * [0 0 g] = <b>R</b> * <b>gravity</b> (g = magnitude of gravity)
* <p><b>R</b> is the identity matrix when the device is aligned with the * <p>
* [0 m 0] = <b>I</b> * <b>R</b> * <b>geomagnetic</b> (m = magnitude of
* geomagnetic field)
* <p>
* <b>R</b> is the identity matrix when the device is aligned with the
* world's coordinate system, that is, when the device's X axis points * world's coordinate system, that is, when the device's X axis points
* toward East, the Y axis points to the North Pole and the device is facing * toward East, the Y axis points to the North Pole and the device is facing
* the sky. * the sky.
* *
* <p><b>I</b> is a rotation matrix transforming the geomagnetic * <p>
* vector into the same coordinate space as gravity (the world's coordinate * <b>I</b> is a rotation matrix transforming the geomagnetic vector into
* space). <b>I</b> is a simple rotation around the X axis. * the same coordinate space as gravity (the world's coordinate space).
* The inclination angle in radians can be computed with * <b>I</b> is a simple rotation around the X axis. The inclination angle in
* {@link #getInclination}. * radians can be computed with {@link #getInclination}.
* <hr> * <hr>
* *
* <p> Each matrix is returned either as a 3x3 or 4x4 row-major matrix * <p>
* depending on the length of the passed array: * Each matrix is returned either as a 3x3 or 4x4 row-major matrix depending
* <p><u>If the array length is 16:</u> * on the length of the passed array:
* <p>
* <u>If the array length is 16:</u>
*
* <pre> * <pre>
* / M[ 0] M[ 1] M[ 2] M[ 3] \ * / M[ 0] M[ 1] M[ 2] M[ 3] \
* | M[ 4] M[ 5] M[ 6] M[ 7] | * | M[ 4] M[ 5] M[ 6] M[ 7] |
* | M[ 8] M[ 9] M[10] M[11] | * | M[ 8] M[ 9] M[10] M[11] |
* \ M[12] M[13] M[14] M[15] / * \ M[12] M[13] M[14] M[15] /
*</pre> *</pre>
* This matrix is ready to be used by OpenGL ES's *
* {@link javax.microedition.khronos.opengles.GL10#glLoadMatrixf(float[], int) * This matrix is ready to be used by OpenGL ES's
* glLoadMatrixf(float[], int)}. * {@link javax.microedition.khronos.opengles.GL10#glLoadMatrixf(float[], int)
* <p>Note that because OpenGL matrices are column-major matrices you must * glLoadMatrixf(float[], int)}.
* transpose the matrix before using it. However, since the matrix is a * <p>
* Note that because OpenGL matrices are column-major matrices you must
* transpose the matrix before using it. However, since the matrix is a
* rotation matrix, its transpose is also its inverse, conveniently, it is * rotation matrix, its transpose is also its inverse, conveniently, it is
* often the inverse of the rotation that is needed for rendering; it can * often the inverse of the rotation that is needed for rendering; it can
* therefore be used with OpenGL ES directly. * therefore be used with OpenGL ES directly.
* <p> * <p>
* Also note that the returned matrices always have this form: * Also note that the returned matrices always have this form:
*
* <pre> * <pre>
* / M[ 0] M[ 1] M[ 2] 0 \ * / M[ 0] M[ 1] M[ 2] 0 \
* | M[ 4] M[ 5] M[ 6] 0 | * | M[ 4] M[ 5] M[ 6] 0 |
* | M[ 8] M[ 9] M[10] 0 | * | M[ 8] M[ 9] M[10] 0 |
* \ 0 0 0 1 / * \ 0 0 0 1 /
*</pre> *</pre>
* <p><u>If the array length is 9:</u> *
* <p>
* <u>If the array length is 9:</u>
*
* <pre> * <pre>
* / M[ 0] M[ 1] M[ 2] \ * / M[ 0] M[ 1] M[ 2] \
* | M[ 3] M[ 4] M[ 5] | * | M[ 3] M[ 4] M[ 5] |
* \ M[ 6] M[ 7] M[ 8] / * \ M[ 6] M[ 7] M[ 8] /
*</pre> *</pre>
* *
* <hr> * <hr>
* <p>The inverse of each matrix can be computed easily by taking its * <p>
* The inverse of each matrix can be computed easily by taking its
* transpose. * transpose.
* *
* <p>The matrices returned by this function are meaningful only when the * <p>
* device is not free-falling and it is not close to the magnetic north. * The matrices returned by this function are meaningful only when the
* If the device is accelerating, or placed into a strong magnetic field, * device is not free-falling and it is not close to the magnetic north. If
* the returned matrices may be inaccurate. * the device is accelerating, or placed into a strong magnetic field, the
* * returned matrices may be inaccurate.
* @param R is an array of 9 floats holding the rotation matrix <b>R</b> *
* when this function returns. R can be null.<p> * @param R
* @param I is an array of 9 floats holding the rotation matrix <b>I</b> * is an array of 9 floats holding the rotation matrix <b>R</b> when
* when this function returns. I can be null.<p> * this function returns. R can be null.
* @param gravity is an array of 3 floats containing the gravity vector * <p>
* expressed in the device's coordinate. You can simply use the *
* {@link android.hardware.SensorEvent#values values} * @param I
* returned by a {@link android.hardware.SensorEvent SensorEvent} of a * is an array of 9 floats holding the rotation matrix <b>I</b> when
* {@link android.hardware.Sensor Sensor} of type * this function returns. I can be null.
* {@link android.hardware.Sensor#TYPE_ACCELEROMETER TYPE_ACCELEROMETER}.<p> * <p>
* @param geomagnetic is an array of 3 floats containing the geomagnetic *
* vector expressed in the device's coordinate. You can simply use the * @param gravity
* {@link android.hardware.SensorEvent#values values} * is an array of 3 floats containing the gravity vector expressed in
* returned by a {@link android.hardware.SensorEvent SensorEvent} of a * the device's coordinate. You can simply use the
* {@link android.hardware.Sensor Sensor} of type * {@link android.hardware.SensorEvent#values values} returned by a
* {@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD TYPE_MAGNETIC_FIELD}. * {@link android.hardware.SensorEvent SensorEvent} of a
* @return * {@link android.hardware.Sensor Sensor} of type
* true on success<p> * {@link android.hardware.Sensor#TYPE_ACCELEROMETER
* false on failure (for instance, if the device is in free fall). * TYPE_ACCELEROMETER}.
* On failure the output matrices are not modified. * <p>
*
* @param geomagnetic
* is an array of 3 floats containing the geomagnetic vector
* expressed in the device's coordinate. You can simply use the
* {@link android.hardware.SensorEvent#values values} returned by a
* {@link android.hardware.SensorEvent SensorEvent} of a
* {@link android.hardware.Sensor Sensor} of type
* {@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
* TYPE_MAGNETIC_FIELD}.
*
* @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.
*/ */
public static boolean getRotationMatrix(float[] R, float[] I, public static boolean getRotationMatrix(float[] R, float[] I,
@@ -1160,7 +1289,9 @@ public class SensorManager
/** /**
* Computes the geomagnetic inclination angle in radians from the * Computes the geomagnetic inclination angle in radians from the
* inclination matrix <b>I</b> returned by {@link #getRotationMatrix}. * inclination matrix <b>I</b> returned by {@link #getRotationMatrix}.
* @param I inclination matrix see {@link #getRotationMatrix}. *
* @param I
* inclination matrix see {@link #getRotationMatrix}.
* @return The geomagnetic inclination angle in radians. * @return The geomagnetic inclination angle in radians.
*/ */
public static float getInclination(float[] I) { public static float getInclination(float[] I) {
@@ -1172,52 +1303,76 @@ public class SensorManager
} }
/** /**
* Rotates the supplied rotation matrix so it is expressed in a * <p>
* different coordinate system. This is typically used when an application * Rotates the supplied rotation matrix so it is expressed in a different
* needs to compute the three orientation angles of the device (see * coordinate system. This is typically used when an application needs to
* compute the three orientation angles of the device (see
* {@link #getOrientation}) in a different coordinate system. * {@link #getOrientation}) in a different coordinate system.
* </p>
*
* <p>
* When the rotation matrix is used for drawing (for instance with OpenGL
* ES), it usually <b>doesn't need</b> to be transformed by this function,
* unless the screen is physically rotated, in which case you can use
* {@link android.view.Display#getRotation() Display.getRotation()} to
* retrieve the current rotation of the screen. Note that because the user
* is generally free to rotate their screen, you often should consider the
* rotation in deciding the parameters to use here.
* </p>
*
* <p>
* <u>Examples:</u>
* <p>
*
* <ul>
* <li>Using the camera (Y axis along the camera's axis) for an augmented
* reality application where the rotation angles are needed:</li>
*
* <p>
* <ul>
* <code>remapCoordinateSystem(inR, AXIS_X, AXIS_Z, outR);</code>
* </ul>
* </p>
* *
* <p>When the rotation matrix is used for drawing (for instance with
* OpenGL ES), it usually <b>doesn't need</b> to be transformed by this
* function, unless the screen is physically rotated, in which case you
* can use {@link android.view.Display#getRotation() Display.getRotation()}
* to retrieve the current rotation of the screen. Note that because the
* user is generally free to rotate their screen, you often should
* consider the rotation in deciding the parameters to use here.
*
* <p><u>Examples:</u><p>
*
* <li>Using the camera (Y axis along the camera's axis) for an augmented
* reality application where the rotation angles are needed: </li><p>
*
* <code>remapCoordinateSystem(inR, AXIS_X, AXIS_Z, outR);</code><p>
*
* <li>Using the device as a mechanical compass when rotation is * <li>Using the device as a mechanical compass when rotation is
* {@link android.view.Surface#ROTATION_90 Surface.ROTATION_90}:</li><p> * {@link android.view.Surface#ROTATION_90 Surface.ROTATION_90}:</li>
* *
* <code>remapCoordinateSystem(inR, AXIS_Y, AXIS_MINUS_X, outR);</code><p> * <p>
* * <ul>
* Beware of the above example. This call is needed only to account for * <code>remapCoordinateSystem(inR, AXIS_Y, AXIS_MINUS_X, outR);</code>
* a rotation from its natural orientation when calculating the * </ul>
* rotation angles (see {@link #getOrientation}). * </p>
* If the rotation matrix is also used for rendering, it may not need to *
* be transformed, for instance if your {@link android.app.Activity * Beware of the above example. This call is needed only to account for a
* Activity} is running in landscape mode. * rotation from its natural orientation when calculating the rotation
* * angles (see {@link #getOrientation}). If the rotation matrix is also used
* <p>Since the resulting coordinate system is orthonormal, only two axes * for rendering, it may not need to be transformed, for instance if your
* need to be specified. * {@link android.app.Activity Activity} is running in landscape mode.
* * </ul>
* @param inR the rotation matrix to be transformed. Usually it is the *
* matrix returned by {@link #getRotationMatrix}. * <p>
* @param X defines on which world axis and direction the X axis of the * Since the resulting coordinate system is orthonormal, only two axes need
* device is mapped. * to be specified.
* @param Y defines on which world axis and direction the Y axis of the *
* device is mapped. * @param inR
* @param outR the transformed rotation matrix. inR and outR can be the same * the rotation matrix to be transformed. Usually it is the matrix
* returned by {@link #getRotationMatrix}.
*
* @param X
* defines on which world axis and direction the X axis of the device
* is mapped.
*
* @param Y
* defines on which world axis and direction the Y axis of the device
* is mapped.
*
* @param outR
* the transformed rotation matrix. inR and outR can be the same
* array, but it is not recommended for performance reason. * array, but it is not recommended for performance reason.
* @return true on success. false if the input parameters are incorrect, for *
* instance if X and Y define the same axis. Or if inR and outR don't have * @return <code>true</code> on success. <code>false</code> if the input
* the same length. * parameters are incorrect, for instance if X and Y define the same
* axis. Or if inR and outR don't have the same length.
*/ */
public static boolean remapCoordinateSystem(float[] inR, int X, int Y, public static boolean remapCoordinateSystem(float[] inR, int X, int Y,
@@ -1301,19 +1456,24 @@ public class SensorManager
/** /**
* Computes the device's orientation based on the rotation matrix. * Computes the device's orientation based on the rotation matrix.
* <p> When it returns, the array values is filled with the result: * <p>
* When it returns, the array values is filled with the result:
* <ul>
* <li>values[0]: <i>azimuth</i>, rotation around the Z axis.</li> * <li>values[0]: <i>azimuth</i>, rotation around the Z axis.</li>
* <li>values[1]: <i>pitch</i>, rotation around the X axis.</li> * <li>values[1]: <i>pitch</i>, rotation around the X axis.</li>
* <li>values[2]: <i>roll</i>, rotation around the Y axis.</li> * <li>values[2]: <i>roll</i>, rotation around the Y axis.</li>
* </ul>
* <p> * <p>
* All three angles above are in <b>radians</b> and <b>positive</b> in the * All three angles above are in <b>radians</b> and <b>positive</b> in the
* <b>counter-clockwise</b> direction. * <b>counter-clockwise</b> direction.
* *
* @param R rotation matrix see {@link #getRotationMatrix}. * @param R
* @param values an array of 3 floats to hold the result. * rotation matrix see {@link #getRotationMatrix}.
* @param values
* an array of 3 floats to hold the result.
* @return The array values passed as argument. * @return The array values passed as argument.
*/ */
public static float[] getOrientation(float[] R, float values[]) { public static float[] getOrientation(float[] R, float values[]) {
/* /*
* 4x4 (length=16) case: * 4x4 (length=16) case:
* / R[ 0] R[ 1] R[ 2] 0 \ * / R[ 0] R[ 1] R[ 2] 0 \