Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 74cde2ce authored by Mathias Agopian's avatar Mathias Agopian
Browse files

Improve SensorManager documentation 

this pass is mostly just formating.

Change-Id: Ica7dd014c301817c93e915c08b16da99769eaabb
parent 2d468c5d

core/java/android/hardware/Sensor.java

+40 −44
Original line number Diff line number Diff line
@@ -18,29 +18,27 @@ 
package android.hardware;



/**

 * Class representing a sensor. Use {@link SensorManager#getSensorList}

 * to get the list of available Sensors.

 * Class representing a sensor. Use {@link SensorManager#getSensorList} to get

 * the list of available Sensors.

 */

public class Sensor {



    /**

     * A constant describing an accelerometer sensor type.

     * See {@link android.hardware.SensorEvent SensorEvent}

     * for more details.

     * A constant describing an accelerometer sensor type. See

     * {@link android.hardware.SensorEvent SensorEvent} for more details.

     */

    public static final int TYPE_ACCELEROMETER = 1;



    /**

     * A constant describing a magnetic field sensor type.

     * See {@link android.hardware.SensorEvent SensorEvent}

     * for more details.

     * A constant describing a magnetic field sensor type. See

     * {@link android.hardware.SensorEvent SensorEvent} for more details.

     */

    public static final int TYPE_MAGNETIC_FIELD = 2;



    /**

     * A constant describing an orientation sensor type.

     * See {@link android.hardware.SensorEvent SensorEvent}

     * for more details.

     * A constant describing an orientation sensor type. See

     * {@link android.hardware.SensorEvent SensorEvent} for more details.

     *

     * @deprecated use {@link android.hardware.SensorManager#getOrientation

     *             SensorManager.getOrientation()} instead.

     */
@@ -49,10 +47,10 @@ public class Sensor { 


    /** A constant describing a gyroscope sensor type */

    public static final int TYPE_GYROSCOPE = 4;



    /**

     * A constant describing an light sensor type.

     * See {@link android.hardware.SensorEvent SensorEvent}

     * for more details.

     * A constant describing an light sensor type. See

     * {@link android.hardware.SensorEvent SensorEvent} for more details.

     */

    public static final int TYPE_LIGHT = 5;
@@ -63,13 +61,11 @@ public class Sensor { 
    public static final int TYPE_TEMPERATURE = 7;



    /**

     * A constant describing an proximity sensor type.

     * See {@link android.hardware.SensorEvent SensorEvent}

     * for more details.

     * A constant describing an proximity sensor type. See

     * {@link android.hardware.SensorEvent SensorEvent} for more details.

     */

    public static final int TYPE_PROXIMITY = 8;



    

    /**

     * A constant describing all sensor types.

     */

core/java/android/hardware/SensorEvent.java

+132 −97
Original line number Diff line number Diff line
@@ -17,26 +17,36 @@ 
package android.hardware;



/**

 * This class represents a sensor event and holds informations such as the

 * sensor type (eg: accelerometer, orientation, etc...), the time-stamp, 

 * accuracy and of course the sensor's {@link SensorEvent#values data}.

 *

 * <p><u>Definition of the coordinate system used by the SensorEvent API.</u><p>

 * 

 * <pre>

 * 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 orientation changes.

 * 

 * 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>

 * This class represents a {@link android.hardware.Sensor Sensor} event and

 * 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>

 * 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

 * orientation changes.

 * </p>

 *

 * <p>

 * 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

 * Android 2D APIs where the origin is in the top-left corner.

 * </p>

 *

 * <pre>

 *   x<0         x>0

 *                ^

 *                |
@@ -60,90 +70,115 @@ package android.hardware; 


public class SensorEvent {

    /**

     * <p>

     * The length and contents of the values array vary depending on which

     * sensor type is being monitored (see also {@link SensorEvent} for a 

     * definition of the coordinate system used):

     * 

     * <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), 

     * 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>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> This sensor type exists for legacy reasons, please use

     * {@link android.hardware.Sensor sensor} type is being monitored (see also

     * {@link SensorEvent} for a definition of the coordinate system used):

     * </p>

     *

     * <h3>{@link android.hardware.Sensor#TYPE_ORIENTATION

     * Sensor.TYPE_ORIENTATION}:</h3> All values are angles in degrees.

     *

     * <ul>

     * <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), 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>toward</b> the z-axis.

     * </ul>

     *

     * <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> 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.

     * {@link android.hardware.SensorManager#getOrientation getOrientation()} to

     * compute these values instead.

     *

     * <p>{@link android.hardware.Sensor#TYPE_ACCELEROMETER Sensor.TYPE_ACCELEROMETER}:<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]: 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>

     * <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>

     * <u>Examples</u>:

     * <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>

     * +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>

     * 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>

     *

     *

     * <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.

     * <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.

     *

     * <p>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:<p>

     * <h3>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h3>

     *

     *  <p>values[0]: Ambient light level in SI lux units

     * <ul>

     * <p>

     * values[0]: Ambient light level in SI lux units

     * </ul>

     *

     * <p>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:<p>

     * <h3>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:

     * </h3>

     *

     *  <p>values[0]: Proximity sensor distance measured in centimeters

     * <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.

     * <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;



    /**

     * The sensor that generated this event.

     * See {@link android.hardware.SensorManager SensorManager}

     * for details.

     * The sensor that generated this event. See

     * {@link android.hardware.SensorManager SensorManager} for details.

     */

   public Sensor sensor;



    /**

     * The accuracy of this event.

     * See {@link android.hardware.SensorManager SensorManager}

     * for details.

     * The accuracy of this event. See {@link android.hardware.SensorManager

     * SensorManager} for details.

     */

    public int accuracy;

core/java/android/hardware/SensorManager.java

+378 −218

File changed.

Preview size limit exceeded, changes collapsed.