From 086d840d7403120c2109bb73202e27079dd54dec Mon Sep 17 00:00:00 2001
From: Brian Duddie <bduddie@google.com>
Date: Wed, 5 Jun 2019 11:41:40 -0700
Subject: [PATCH] Clarify documentation for sensor placement

Update documentation to be in sync with new language added to HAL
interface, which better explains the expected payload, format, and
usage.

Fixes: 133264933
Test: make docs, view HTML
Change-Id: Ib602674d395cb8c8e6431d23b051685c8d172560
---
 .../hardware/SensorAdditionalInfo.java        | 48 +++++++++++++++++--
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/core/java/android/hardware/SensorAdditionalInfo.java b/core/java/android/hardware/SensorAdditionalInfo.java
index 5ff627f48017c..12edc5eb7e33f 100644
--- a/core/java/android/hardware/SensorAdditionalInfo.java
+++ b/core/java/android/hardware/SensorAdditionalInfo.java
@@ -119,12 +119,50 @@ public class SensorAdditionalInfo {
     public static final int TYPE_VEC3_CALIBRATION = 0x10002;
 
     /**
-     * Sensor placement. Describes location and installation angle of the sensor device.
+     * Sensor placement.
      *
-     * Payload:
-     *     floatValues[0..11]: First 3 rows of homogeneous matrix in row major order that describes
-     *     the location and orientation of the sensor. Origin of reference will be the mobile device
-     *     geometric sensor. Reference frame is defined as the same as Android sensor frame.
+     * Provides the orientation and location of the sensor element in terms of the
+     * Android coordinate system. This data is given as a 3x4 matrix consisting of a 3x3 rotation
+     * matrix (R) concatenated with a 3x1 location vector (t). The rotation matrix provides the
+     * orientation of the Android device coordinate frame relative to the local coordinate frame of
+     * the sensor. Note that assuming the axes conventions of the sensor are the same as Android,
+     * this is the inverse of the matrix applied to raw samples read from the sensor to convert them
+     * into the Android representation. The location vector represents the translation from the
+     * origin of the Android sensor coordinate system to the geometric center of the sensor,
+     * specified in millimeters (mm).
+     * <p>
+     * <b>Payload</b>:
+     *     <code>floatValues[0..11]</code>: 3x4 matrix in row major order [R; t]
+     * </p>
+     * <p>
+     * <b>Example</b>:
+     *     This raw buffer: <code>{0, 1, 0, 0, -1, 0, 0, 10, 0, 0, 1, -2.5}</code><br>
+     *     Corresponds to this 3x4 matrix:
+     *     <table>
+     *      <thead>
+     *       <tr><td colspan="3">Orientation</td><td>Location</tr>
+     *      </thead>
+     *      <tbody>
+     *       <tr><td>0</td><td>1</td><td>0</td><td>0</td></tr>
+     *       <tr><td>-1</td><td>0</td><td>0</td><td>10</td></tr>
+     *       <tr><td>0</td><td>0</td><td>1</td><td>-2.5</td></tr>
+     *      </tbody>
+     *     </table>
+     *     The sensor is oriented such that:
+     *     <ul>
+     *        <li>The device X axis corresponds to the sensor's local -Y axis
+     *        <li>The device Y axis corresponds to the sensor's local X axis
+     *        <li>The device Z axis and sensor's local Z axis are equivalent
+     *     </ul>
+     *     In other words, if viewing the origin of the Android coordinate system from the positive
+     *     Z direction, the device coordinate frame is to be rotated 90° counter-clockwise about the
+     *     Z axis to align with the sensor's local coordinate frame. Equivalently, a vector in the
+     *     Android coordinate frame may be multiplied with R to rotate it 90° clockwise (270°
+     *     counter-clockwise), yielding its representation in the sensor's coordinate frame.
+     *     Relative to the origin of the Android coordinate system, the physical center of the
+     *     sensor is located 10mm in the positive Y direction, and 2.5mm in the negative Z
+     *     direction.
+     * </p>
      */
     public static final int TYPE_SENSOR_PLACEMENT = 0x10003;