[2472946] Sensor.TYPE_ORIENTATION returns inverted roll values
Fix the documentation to reflect reality and encourage developpers to use
SensorManager.getRotation() instead of using Sensor.TYPE_ORIENTATION
diff --git a/core/java/android/hardware/Sensor.java b/core/java/android/hardware/Sensor.java
index f5fed4f..bb209f3 100644
--- a/core/java/android/hardware/Sensor.java
+++ b/core/java/android/hardware/Sensor.java
@@ -52,10 +52,13 @@
* for more details.
*/
public static final int TYPE_LIGHT = 5;
+
/** A constant describing a pressure sensor type */
public static final int TYPE_PRESSURE = 6;
+
/** A constant describing a temperature sensor type */
public static final int TYPE_TEMPERATURE = 7;
+
/**
* A constant describing an proximity sensor type.
* See {@link android.hardware.SensorEvent SensorEvent}
diff --git a/core/java/android/hardware/SensorEvent.java b/core/java/android/hardware/SensorEvent.java
index 32d5691..9a9f0bf 100644
--- a/core/java/android/hardware/SensorEvent.java
+++ b/core/java/android/hardware/SensorEvent.java
@@ -68,27 +68,30 @@
* 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).
+ * 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),
* with positive values when the z-axis moves <b>toward</b> the y-axis.
*
* <p>values[2]: Roll, rotation around Y axis (-90 to 90), with
- * positive values when the x-axis moves <b>away</b> from the z-axis.
+ * positive values when the x-axis moves <b>toward</b> the z-axis.
*
+ * <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><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><b>Note:</b> It is preferable to use
+ *
+ * <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; while it may be more expensive, it is usually
- * more accurate.
+ * to compute these values instead.
*
* <p>{@link android.hardware.Sensor#TYPE_ACCELEROMETER Sensor.TYPE_ACCELEROMETER}:<p>
* All values are in SI units (m/s^2) and measure the acceleration applied
diff --git a/core/java/android/hardware/SensorManager.java b/core/java/android/hardware/SensorManager.java
index 1fe5dc3..aebe84e 100644
--- a/core/java/android/hardware/SensorManager.java
+++ b/core/java/android/hardware/SensorManager.java
@@ -1306,6 +1306,8 @@
* <li>values[1]: <i>pitch</i>, rotation around the X axis.</li>
* <li>values[2]: <i>roll</i>, rotation around the Y axis.</li>
* <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.