allow rotation-vector to have 4 components

- upadte documentation for rotation vector
- update method dealing with rotation vector to deal with 4 components
- virtual rotation-vector sensor reports all four components
- improve SensorManager documentation layout

Whent he 4-th component of the rotation-vector is present, we can save
a square-root when computing the quaternion or rotation matrix from it.

Change-Id: Ia84d278dd5f0909fab1c5ba050f8df2679e2c7c8

2 files changed, 49 insertions, 20 deletions

diff --git a/core/java/android/hardware/SensorEvent.java b/core/java/android/hardware/SensorEvent.java
index 32ff3b3..8c55bf3 100644
--- a/core/java/android/hardware/SensorEvent.java
+++ b/core/java/android/hardware/SensorEvent.java
@@ -220,25 +220,47 @@ public class SensorEvent {
      * </p>
      * 
      *  <h4>{@link android.hardware.Sensor#TYPE_GRAVITY Sensor.TYPE_GRAVITY}:</h4>
-     *  A three dimensional vector indicating the direction and magnitude of gravity.  Units
-     *  are m/s^2.  The coordinate system is the same as is used by the acceleration sensor.
+     *  <p>A three dimensional vector indicating the direction and magnitude of gravity.  Units
+     *  are m/s^2. The coordinate system is the same as is used by the acceleration sensor.</p>
+     *  <p><b>Note:</b> When the device is at rest, the output of the gravity sensor should be identical
+     *  to that of the accelerometer.</p>
      *
      *  <h4>{@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION Sensor.TYPE_LINEAR_ACCELERATION}:</h4>
      *  A three dimensional vector indicating acceleration along each device axis, not including
      *  gravity.  All values have units of m/s^2.  The coordinate system is the same as is used by the
-     * acceleration sensor.
+     *  acceleration sensor.
+     *  <p>The output of the accelerometer, gravity and  linear-acceleration sensors must obey the
+     *  following relation:</p>
+     *   <p><ul>acceleration = gravity + linear-acceleration</ul></p>
      *
      *  <h4>{@link android.hardware.Sensor#TYPE_ROTATION_VECTOR Sensor.TYPE_ROTATION_VECTOR}:</h4>
-     *  The rotation vector represents the orientation of the device as a combination of an angle
-     *  and an axis, in which the device has rotated through an angle theta around an axis
-     *  &lt;x, y, z>. The three elements of the rotation vector are
-     *  &lt;x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude of the rotation
-     *  vector is equal to sin(theta/2), and the direction of the rotation vector is equal to the
-     *  direction of the axis of rotation. The three elements of the rotation vector are equal to
-     *  the last three components of a unit quaternion
-     *  &lt;cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>.  Elements of the rotation
-     *  vector are unitless.  The x,y, and z axis are defined in the same way as the acceleration
-     *  sensor.
+     *  <p>The rotation vector represents the orientation of the device as a combination of an <i>angle</i>
+     *  and an <i>axis</i>, in which the device has rotated through an angle &#952 around an axis
+     *  &lt;x, y, z>.</p>
+     *  <p>The three elements of the rotation vector are
+     *  &lt;x*sin(&#952/2), y*sin(&#952/2), z*sin(&#952/2)>, such that the magnitude of the rotation
+     *  vector is equal to sin(&#952/2), and the direction of the rotation vector is equal to the
+     *  direction of the axis of rotation.</p>
+     *  </p>The three elements of the rotation vector are equal to
+     *  the last three components of a <b>unit</b> quaternion
+     *  &lt;cos(&#952/2), x*sin(&#952/2), y*sin(&#952/2), z*sin(&#952/2)>.</p>
+     *  <p>Elements of the rotation vector are unitless.
+     *  The x,y, and z axis are defined in the same way as the acceleration
+     *  sensor.</p>
+     * <ul>
+     * <p>
+     * values[0]: x*sin(&#952/2)
+     * </p>
+     * <p>
+     * values[1]: y*sin(&#952/2)
+     * </p>
+     * <p>
+     * values[2]: z*sin(&#952/2)
+     * </p>
+     * <p>
+     * values[3]: cos(&#952/2) <i>(optional: only if value.length = 4)</i>
+     * </p>
+     * </ul>
      *
      * <h4>{@link android.hardware.Sensor#TYPE_ORIENTATION
      * Sensor.TYPE_ORIENTATION}:</h4> All values are angles in degrees.
diff --git a/core/java/android/hardware/SensorManager.java b/core/java/android/hardware/SensorManager.java
index c178aee..1b799ae 100644
--- a/core/java/android/hardware/SensorManager.java
+++ b/core/java/android/hardware/SensorManager.java
@@ -1938,13 +1938,18 @@ public class SensorManager
      *  @param R an array of floats in which to store the rotation matrix
      */
     public static void getRotationMatrixFromVector(float[] R, float[] rotationVector) {
-        float q0 = (float)Math.sqrt(1 - rotationVector[0]*rotationVector[0] -
-                                    rotationVector[1]*rotationVector[1] -
-                                    rotationVector[2]*rotationVector[2]);
+
+        float q0;
         float q1 = rotationVector[0];
         float q2 = rotationVector[1];
         float q3 = rotationVector[2];
 
+        if (rotationVector.length == 4) {
+            q0 = rotationVector[3];
+        } else {
+            q0 = (float)Math.sqrt(1 - q1*q1 - q2*q2 - q3*q3);
+        }
+
         float sq_q1 = 2 * q1 * q1;
         float sq_q2 = 2 * q2 * q2;
         float sq_q3 = 2 * q3 * q3;
@@ -1995,10 +2000,12 @@ public class SensorManager
      *  @param Q an array of floats in which to store the computed quaternion
      */
     public static void getQuaternionFromVector(float[] Q, float[] rv) {
-        float w = (float)Math.sqrt(1 - rv[0]*rv[0] - rv[1]*rv[1] - rv[2]*rv[2]);
-        //In this case, the w component of the quaternion is known to be a positive number
-
-        Q[0] = w;
+        if (rv.length == 4) {
+            Q[0] = rv[3];
+        } else {
+            //In this case, the w component of the quaternion is known to be a positive number
+            Q[0] = (float)Math.sqrt(1 - rv[0]*rv[0] - rv[1]*rv[1] - rv[2]*rv[2]);
+        }
         Q[1] = rv[0];
         Q[2] = rv[1];
         Q[3] = rv[2];