Merge \\\\"docs: Updated descriptions of device orientation angles.\\\\" into mnc-docs am: d312201b74 am: 6b4d2a2e6d am: a812012c52

am: b9487874fe

Change-Id: I034ce5c4a115fa4b694569c66a7e764543191cf7

2 files changed, 202 insertions, 106 deletions

diff --git a/core/java/android/hardware/SensorManager.java b/core/java/android/hardware/SensorManager.java
index a20307a868c7..04ee1e6d57d0 100644
--- a/core/java/android/hardware/SensorManager.java
+++ b/core/java/android/hardware/SensorManager.java
@@ -1356,20 +1356,35 @@ public abstract class SensorManager {
     /**
      * Computes the device's orientation based on the rotation matrix.
      * <p>
-     * When it returns, the array values is filled with the result:
+     * When it returns, the array values are as follows:
      * <ul>
-     * <li>values[0]: <i>azimuth</i>, rotation around the -Z axis,
-     *                i.e. the opposite direction of Z axis.</li>
-     * <li>values[1]: <i>pitch</i>, rotation around the -X axis,
-     *                i.e the opposite direction of X axis.</li>
-     * <li>values[2]: <i>roll</i>, rotation around the Y axis.</li>
+     * <li>values[0]: <i>Azimuth</i>, angle of rotation about the -z axis.
+     *                This value represents the angle between the device's y
+     *                axis and the magnetic north pole. When facing north, this
+     *                angle is 0, when facing south, this angle is &pi;.
+     *                Likewise, when facing east, this angle is &pi;/2, and
+     *                when facing west, this angle is -&pi;/2. The range of
+     *                values is -&pi; to &pi;.</li>
+     * <li>values[1]: <i>Pitch</i>, angle of rotation about the x axis.
+     *                This value represents the angle between a plane parallel
+     *                to the device's screen and a plane parallel to the ground.
+     *                Assuming that the bottom edge of the device faces the
+     *                user and that the screen is face-up, tilting the top edge
+     *                of the device toward the ground creates a positive pitch
+     *                angle. The range of values is -&pi; to &pi;.</li>
+     * <li>values[2]: <i>Roll</i>, angle of rotation about the y axis. This
+     *                value represents the angle between a plane perpendicular
+     *                to the device's screen and a plane perpendicular to the
+     *                ground. Assuming that the bottom edge of the device faces
+     *                the user and that the screen is face-up, tilting the left
+     *                edge of the device toward the ground creates a positive
+     *                roll angle. The range of values is -&pi;/2 to &pi;/2.</li>
      * </ul>
      * <p>
-     * Applying these three intrinsic rotations in azimuth, pitch and roll order transforms
-     * identity matrix to the rotation matrix given in input R.
-     * All three angles above are in <b>radians</b> and <b>positive</b> in the
-     * <b>counter-clockwise</b> direction. Range of output is: azimuth from -&pi; to &pi;,
-     * pitch from -&pi;/2 to &pi;/2 and roll from -&pi; to &pi;.
+     * Applying these three rotations in the azimuth, pitch, roll order
+     * transforms an identity matrix to the rotation matrix passed into this
+     * method. Also, note that all three orientation angles are expressed in
+     * <b>radians</b>.
      *
      * @param R
      *        rotation matrix see {@link #getRotationMatrix}.
diff --git a/docs/html/guide/topics/sensors/sensors_position.jd b/docs/html/guide/topics/sensors/sensors_position.jd
index d0ddeadf2166..5ec16c71537c 100644
--- a/docs/html/guide/topics/sensors/sensors_position.jd
+++ b/docs/html/guide/topics/sensors/sensors_position.jd
@@ -8,7 +8,7 @@ page.tags=sensorevent,orientation,proximity
   <ol>
     <li><a href="#sensors-pos-gamerot">Using the Game Rotation Vector Sensor</a></li>
     <li><a href="#sensors-pos-geomrot">Using the Geomagnetic Rotation Vector Sensor</a></li>
-    <li><a href="#sensors-pos-orient">Using the Orientation Sensor</a></li>
+    <li><a href="#sensors-pos-orient">Computing the Device's Orientation</a></li>
     <li><a href="#sensors-pos-mag">Using the Geomagnetic Field Sensor</a></li>
     <li><a href="#sensors-pos-prox">Using the Proximity Sensor</a></li>
   </ol>
@@ -42,38 +42,49 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/Senso
   </div>
 </div>
 
-<p>The Android platform provides two sensors that let you determine the position of a device: the
-geomagnetic field sensor and the orientation sensor. The Android platform also
-provides a sensor that lets you determine how close the face of a device is to an object (known as
-the proximity sensor). The geomagnetic field sensor and the proximity sensor are hardware-based.
-Most
-handset and tablet manufacturers include a geomagnetic field sensor. Likewise, handset manufacturers
-usually include a proximity sensor to determine when a handset is being held close to a user's face
-(for example, during a phone call). The orientation sensor is software-based and derives its data
-from the accelerometer and the geomagnetic field sensor.</p>
-
-<p class="note"><strong>Note:</strong> The orientation sensor was deprecated in Android 2.2 (API
-Level 8).</p>
-
-<p>Position sensors are useful for determining a device's physical position in the
-world's frame of reference. For example, you can use the geomagnetic field sensor in
-combination with the accelerometer to determine a device's position relative to
-the magnetic North Pole. You can also use the orientation sensor (or similar sensor-based
-orientation methods) to determine a device's position in your application's frame of reference.
-Position sensors are not typically used to monitor device movement or motion, such as shake, tilt,
-or thrust (for more information, see <a
-href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion Sensors</a>).</p>
-
-<p>The geomagnetic field sensor and orientation sensor return multi-dimensional arrays of sensor
-values
-for each {@link android.hardware.SensorEvent}. For example, the orientation sensor provides
-geomagnetic
-field strength values for each of the three coordinate axes during a single sensor event. Likewise,
-the orientation sensor provides azimuth (yaw), pitch, and roll values during a single sensor event.
-For more information about the coordinate systems that are used by sensors, see <a
-href="{@docRoot}guide/topics/sensors/sensors_overview.html#sensors-coords">Sensor Coordinate
-Systems</a>. The proximity sensor provides a single value for each sensor event. Table 1 summarizes
-the position sensors that are supported on the Android platform.</p>
+<p>
+  The Android platform provides two sensors that let you determine the position
+  of a device: the geomagnetic field sensor and the accelerometer. The Android
+  platform also provides a sensor that lets you determine how close the face of
+  a device is to an object (known as the <em>proximity sensor</em>). The
+  geomagnetic field sensor and the proximity sensor are hardware-based. Most
+  handset and tablet manufacturers include a geomagnetic field sensor. Likewise,
+  handset manufacturers usually include a proximity sensor to determine when a
+  handset is being held close to a user's face (for example, during a phone
+  call). For determining a device's orientation, you can use the readings from
+  the device's accelerometer and the geomagnetic field sensor.
+</p>
+
+<p class="note">
+  <strong>Note:</strong> The orientation sensor was deprecated in Android 2.2
+  (API level 8), and the orientation sensor type was deprecated in Android 4.4W
+  (API level 20).
+</p>
+
+<p>
+  Position sensors are useful for determining a device's physical position in
+  the world's frame of reference. For example, you can use the geomagnetic field
+  sensor in combination with the accelerometer to determine a device's position
+  relative to the magnetic north pole. You can also use these sensors to
+  determine a device's orientation in your application's frame of reference.
+  Position sensors are not typically used to monitor device movement or motion,
+  such as shake, tilt, or thrust (for more information, see <a
+  href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion Sensors</a>).
+</p>
+
+<p>
+  The geomagnetic field sensor and accelerometer return multi-dimensional arrays
+  of sensor values for each {@link android.hardware.SensorEvent}. For example,
+  the geomagnetic field sensor provides geomagnetic field strength values for
+  each of the three coordinate axes during a single sensor event. Likewise, the
+  accelerometer sensor measures the acceleration applied to the device during a
+  sensor event. For more information about the coordinate systems that are used
+  by sensors, see <a
+  href="{@docRoot}guide/topics/sensors/sensors_overview.html#sensors-coords">
+  Sensor Coordinate Systems</a>. The proximity sensor provides a single value
+  for each sensor event. Table 1 summarizes the position sensors that are
+  supported on the Android platform.
+</p>
 
 <p class="table-caption" id="table1">
   <strong>Table 1.</strong> Position sensors that are supported on the Android platform.</p>
@@ -174,14 +185,17 @@ the position sensors that are supported on the Android platform.</p>
   </tr>
 </table>
 
-<p class="note"><sup><strong>1</strong></sup> This sensor was deprecated in Android 2.2 (API Level
-  8). The sensor framework provides alternate methods for acquiring device orientation, which are
-discussed in <a href="#sensors-pos-orient">Using the Orientation Sensor</a>.</p>
+<p class="note">
+  <sup><strong>1</strong></sup>This sensor was deprecated in Android 2.2 (API
+  level 8), and this sensor type was deprecated in Android 4.4W (API level 20).
+  The sensor framework provides alternate methods for acquiring device
+  orientation, which are discussed in <a href="#sensors-pos-orient">Computing
+  the Device's Orientation</a>.
+</p>
 
 <p class="note"><sup><strong>2</strong></sup> Some proximity sensors provide only binary values
 representing near and far.</p>
 
-
 <h2 id="sensors-pos-gamerot">Using the Game Rotation Vector Sensor</h2>
 
 <p>The game rotation vector sensor is identical to the
@@ -228,71 +242,106 @@ mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTO
 </pre>
 
 
-<h2 id="sensors-pos-orient">Using the Orientation Sensor</h2>
-
-<p>The orientation sensor lets you monitor the position of a device relative to the earth's frame of
-reference (specifically, magnetic north). The following code shows you how to get an instance of the
-default orientation sensor:</p>
+<h2 id="sensors-pos-orient">Computing the Device's Orientation</h2>
 
+<p>By computing a device's orientation, you can monitor the position of the
+  device relative to the earth's frame of reference (specifically, the magnetic
+  north pole). The following code shows you how to compute a device's
+  orientation:
+</p>
 <pre>
 private SensorManager mSensorManager;
-private Sensor mSensor;
 ...
-mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
-mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION);
+// Rotation matrix based on current readings from accelerometer and magnetometer.
+final float[] rotationMatrix = new float[9];
+mSensorManager.getRotationMatrix(rotationMatrix, null,
+  accelerometerReading, magnetometerReading);
+
+// Express the updated rotation matrix as three orientation angles.
+final float[] orientationAngles = new float[3];
+mSensorManager.getOrientation(rotationMatrix, orientationAngles);
 </pre>
-
-<p>The orientation sensor derives its data by using a device's geomagnetic field sensor in
-combination with a device's accelerometer. Using these two hardware sensors, an orientation sensor
-provides data for the following three dimensions:</p>
-
+<p>The system computes the orientation angles by using a device's geomagnetic
+  field sensor in combination with the device's accelerometer. Using these two
+  hardware sensors, the system provides data for the following three
+  orientation angles:
+</p>
 <ul>
-  <li>Azimuth (degrees of rotation around the z axis). This is the angle between magnetic north
-and the device's y axis. For example, if the device's y axis is aligned with magnetic north
-this value is 0, and if the device's y axis is pointing south this value is 180. Likewise, when
-the y axis is pointing east this value is 90 and when it is pointing west this value is 270.</li>
-  <li>Pitch (degrees of rotation around the x axis). This value is positive when the positive z axis
-rotates toward the positive y axis, and it is negative when the positive z axis
-rotates toward the negative y axis. The range of values is 180 degrees to -180
-degrees.</li>
-  <li>Roll (degrees of rotation around the y axis). This value is positive when the positive z axis
-rotates toward the positive x axis, and it is negative when the positive z axis
-rotates toward the negative x axis. The range of values is 90 degrees to -90
-degrees.</li>
+  <li>
+    <strong>Azimuth (degrees of rotation about the -z axis).</strong> This is
+    the angle between the device's current compass direction and magnetic north.
+    If the top edge of the device faces magnetic north, the azimuth is 0
+    degrees; if the top edge faces south, the azimuth is 180 degrees. Similarly,
+    if the top edge faces east, the azimuth is 90 degrees, and if the top edge
+    faces west, the azimuth is 270 degrees.
+  </li>
+  <li>
+    <strong>Pitch (degrees of rotation about the x axis).</strong> This is the
+    angle between a plane parallel to the device's screen and a plane parallel
+    to the ground. If you hold the device parallel to the ground with the bottom
+    edge closest to you and tilt the top edge of the device toward the ground,
+    the pitch angle becomes positive. Tilting in the opposite direction&mdash;
+    moving the top edge of the device away from the ground&mdash;causes
+    the pitch angle to become negative. The range of values is -180 degrees to
+    180 degrees.
+  </li>
+  <li>
+    <strong>Roll (degrees of rotation about the y axis).</strong> This is the
+    angle between a plane perpendicular to the device's screen and a plane
+    perpendicular to the ground. If you hold the device parallel to the ground
+    with the bottom edge closest to you and tilt the left edge of the device
+    toward the ground, the roll angle becomes positive. Tilting in the opposite
+    direction&mdash;moving the right edge of the device toward the ground&mdash;
+    causes the roll angle to become negative. The range of values is -90 degrees
+    to 90 degrees.
+  </li>
 </ul>
 
-<p>This definition is different from yaw, pitch, and roll used in aviation, where the X axis is
-along the long side of the plane (tail to nose). Also, for historical reasons the roll angle is
-positive in the clockwise direction (mathematically speaking, it should be positive in the
-counter-clockwise direction).</p>
-
-<p>The orientation sensor derives its data by processing the raw sensor data from the accelerometer
-and the geomagnetic field sensor. Because of the heavy processing that is involved, the accuracy and
-precision of the orientation sensor is diminished (specifically, this sensor is only reliable when
-the roll component is 0). As a result, the orientation sensor was deprecated in Android 2.2 (API
-level 8). Instead of using raw data from the orientation sensor, we recommend that you use the
-{@link android.hardware.SensorManager#getRotationMatrix getRotationMatrix()} method in conjunction
-with the {@link android.hardware#getOrientation getOrientation()} method to compute orientation
-values. You can also use the {@link android.hardware.SensorManager#remapCoordinateSystem
-remapCoordinateSystem()} method to translate the orientation values to your application's frame of
-reference.</p>
-
-<p>The following code sample shows how to acquire orientation data directly from the orientation
-sensor. We recommend that you do this only if a device has negligible roll.</p>
-
+<p class="note">
+  <strong>Note:</strong>The sensor's roll definition has changed to reflect the
+  vast majority of implementations in the geosensor ecosystem.
+</p>
+
+<p>
+  Note that these angles work off of a different coordinate system than the
+  one used in aviation (for yaw, pitch, and roll). In the aviation system, the
+  x axis is along the long side of the plane, from tail to nose.
+</p>
+
+<p>
+  The orientation sensor derives its data by processing the raw sensor data
+  from the accelerometer and the geomagnetic field sensor. Because of the heavy
+  processing that is involved, the accuracy and precision of the orientation
+  sensor is diminished. Specifically, this sensor is reliable only when the roll
+  angle is 0. As a result, the orientation sensor was deprecated in Android
+  2.2 (API level 8), and the orientation sensor type was deprecated in Android
+  4.4W (API level 20).
+
+  Instead of using raw data from the orientation sensor, we recommend that you
+  use the {@link android.hardware.SensorManager#getRotationMatrix getRotationMatrix()}
+  method in conjunction with the
+  {@link android.hardware.SensorManager#getOrientation getOrientation()} method
+  to compute orientation values, as shown in the following code sample. As part
+  of this process, you can use the
+  {@link android.hardware.SensorManager#remapCoordinateSystem remapCoordinateSystem()}
+  method to translate the orientation values to your application's frame of
+  reference.
+</p>
 <pre>
 public class SensorActivity extends Activity implements SensorEventListener {
 
   private SensorManager mSensorManager;
-  private Sensor mOrientation;
+  private final float[] mAccelerometerReading = new float[3];
+  private final float[] mMagnetometerReading = new float[3];
+
+  private final float[] mRotationMatrix = new float[9];
+  private final float[] mOrientationAngles = new float[3];
 
   &#64;Override
   public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.main);
-
     mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
-    mOrientation = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION);
   }
 
   &#64;Override
@@ -304,31 +353,63 @@ public class SensorActivity extends Activity implements SensorEventListener {
   &#64;Override
   protected void onResume() {
     super.onResume();
-    mSensorManager.registerListener(this, mOrientation, SensorManager.SENSOR_DELAY_NORMAL);
+
+    // Get updates from the accelerometer and magnetometer at a constant rate.
+    // To make batch operations more efficient and reduce power consumption,
+    // provide support for delaying updates to the application.
+    //
+    // In this example, the sensor reporting delay is small enough such that
+    // the application receives an update before the system checks the sensor
+    // readings again.
+    mSensorManager.registerListener(this, Sensor.TYPE_ACCELEROMETER,
+      SensorManager.SENSOR_DELAY_NORMAL, SensorManager.SENSOR_DELAY_UI);
+    mSensorManager.registerListener(this, Sensor.TYPE_MAGNETIC_FIELD,
+      SensorManager.SENSOR_DELAY_NORMAL, SensorManager.SENSOR_DELAY_UI);
   }
 
   &#64;Override
   protected void onPause() {
     super.onPause();
+
+    // Don't receive any more updates from either sensor.
     mSensorManager.unregisterListener(this);
   }
 
+  // Get readings from accelerometer and magnetometer. To simplify calculations,
+  // consider storing these readings as unit vectors.
   &#64;Override
   public void onSensorChanged(SensorEvent event) {
-    float azimuth_angle = event.values[0];
-    float pitch_angle = event.values[1];
-    float roll_angle = event.values[2];
-    // Do something with these orientation angles.
+    if (event.sensor == Sensor.TYPE_ACCELEROMETER) {
+      System.arraycopy(event.values, 0, mAccelerometerReading,
+        0, mAccelerometerReading.length);
+    }
+    else if (event.sensor == Sensor.TYPE_MAGNETIC_FIELD) {
+      System.arraycopy(event.values, 0, mMagnetometerReading,
+        0, mMagnetometerReading.length);
+    }
+  }
+
+  // Compute the three orientation angles based on the most recent readings from
+  // the device's accelerometer and magnetometer.
+  public void updateOrientationAngles() {
+    // Update rotation matrix, which is needed to update orientation angles.
+    mSensorManager.getRotationMatrix(mRotationMatrix, null,
+      mAccelerometerReading, mMagnetometerReading);
+
+    // "mRotationMatrix" now has up-to-date information.
+
+    mSensorManager.getOrientation(mRotationMatrix, mOrientationAngles);
+
+    // "mOrientationAngles" now has up-to-date information.
   }
 }
 </pre>
 
-<p>You do not usually need to perform any data processing or filtering of the raw data that you
-obtain from an orientation sensor, other than translating the sensor's coordinate system to your
-application's frame of reference. The <a
-href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer Play</a> sample shows
-you how to translate acceleration sensor data into another frame of reference; the technique is
-similar to the one you might use with the orientation sensor.</p>
+<p>
+  You don't usually need to perform any data processing or filtering of the
+  device's raw orientation angles other than translating the sensor's
+  coordinate system to your application's frame of reference.
+</p>
 
 <h2 id="sensors-pos-mag">Using the Geomagnetic Field Sensor</h2>