Merge "Improve SensorManager documentation" into gingerbread (7e73a2ce) · Commits · e / os / android_frameworks_base

core/java/android/hardware/Sensor.java

+40 −44

core/java/android/hardware/SensorEvent.java

+132 −97

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

	/**		/**
	* This class represents a sensor event and holds informations such as the		* <p>
	* sensor type (eg: accelerometer, orientation, etc...), the time-stamp,		* This class represents a {@link android.hardware.Sensor Sensor} event and
	* accuracy and of course the sensor's {@link SensorEvent#values data}.		* holds informations such as the sensor's type, 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>		* </p>
	*		*
	* <pre>		* <p>
	* The coordinate space is defined relative to the screen of the phone		* <u>Definition of the coordinate system used by the SensorEvent API.</u>
	* in its default orientation. The axes are not swapped when the device's		* </p>
	* screen orientation changes.		*
	*		* <p>
	* The OpenGL ES coordinate system is used. The origin is in the		* The coordinate space is defined relative to the screen of the phone in its
	* lower-left corner with respect to the screen, with the X axis horizontal		* default orientation. The axes are not swapped when the device's screen
	* and pointing right, the Y axis vertical and pointing up and the Z axis		* orientation changes.
	* pointing outside the front face of the screen. In this system, coordinates		* </p>
	* behind the screen have negative Z values.		*
	*		* <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		* <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.		* Android 2D APIs where the origin is in the top-left corner.
			* </p>
	*		*
			* <pre>
	* x<0 x>0		* x<0 x>0
	* ^		* ^
	* \|		* \|
	@@ -60,90 +70,115 @@ package android.hardware;

	public class SensorEvent {		public class SensorEvent {
	/**		/**
			* <p>
	* The length and contents of the values array vary depending on which		* The length and contents of the values array vary depending on which
	* sensor type is being monitored (see also {@link SensorEvent} for a		* {@link android.hardware.Sensor sensor} type is being monitored (see also
	* definition of the coordinate system used):		* {@link SensorEvent} for a definition of the coordinate system used):
	*		* </p>
	* <p>{@link android.hardware.Sensor#TYPE_ORIENTATION Sensor.TYPE_ORIENTATION}:<p>		*
	* All values are angles in degrees.		* <h3>{@link android.hardware.Sensor#TYPE_ORIENTATION
	*		* Sensor.TYPE_ORIENTATION}:</h3> 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).		* <ul>
	* 0=North, 90=East, 180=South, 270=West		* <p>
	*		* values[0]: Azimuth, angle between the magnetic north direction and the Y
	* <p>values[1]: Pitch, rotation around X axis (-180 to 180),		* axis, around the Z axis (0 to 359). 0=North, 90=East, 180=South, 270=West
	* with positive values when the z-axis moves <b>toward</b> the y-axis.		*
	*		* <p>
	* <p>values[2]: Roll, rotation around Y axis (-90 to 90), with		* values[1]: Pitch, rotation around X axis (-180 to 180), with positive
	* positive values when the x-axis moves <b>toward</b> the z-axis.		* values when the z-axis moves <b>toward</b> the y-axis.
	*		*
	* <p><b>Important note:</b> For historical reasons the roll angle is		* <p>
	* positive in the clockwise direction (mathematically speaking, it		* values[2]: Roll, rotation around Y axis (-90 to 90), with positive values
	* should be positive in the counter-clockwise direction).		* when the x-axis moves <b>toward</b> the z-axis.
	*		* </ul>
	* <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		* <p>
	* the plane (tail to nose).		* <b>Important note:</b> For historical reasons the roll angle is positive
	*		* in the clockwise direction (mathematically speaking, it should be
	* <p><b>Note:</b> This sensor type exists for legacy reasons, please use		* 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		* {@link android.hardware.SensorManager#getRotationMatrix
	* getRotationMatrix()} in conjunction with		* getRotationMatrix()} in conjunction with
	* {@link android.hardware.SensorManager#remapCoordinateSystem		* {@link android.hardware.SensorManager#remapCoordinateSystem
	* remapCoordinateSystem()} and		* remapCoordinateSystem()} and
	* {@link android.hardware.SensorManager#getOrientation getOrientation()}		* {@link android.hardware.SensorManager#getOrientation getOrientation()} to
	* to compute these values instead.		* 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		* All values are in SI units (m/s^2) and measure the acceleration applied
	* to the phone minus the force of gravity.		* to the phone minus the force of gravity.
	*		*
	* <p>values[0]: Acceleration minus Gx on the x-axis		* <ul>
	* <p>values[1]: Acceleration minus Gy on the y-axis		* <p>
	* <p>values[2]: Acceleration minus Gz on the z-axis		* values[0]: Acceleration minus Gx on the x-axis
	*		* <p>
	* <p><u>Examples</u>:		* values[1]: Acceleration minus Gy on the y-axis
	* <li>When the device lies flat on a table and is pushed on its left		* <p>
	* side toward the right, the x acceleration value is positive.</li>		* 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		* <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)		* +9.81, which correspond to the acceleration of the device (0 m/s^2) minus
	* minus the force of gravity (-9.81 m/s^2).</li>		* 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		* <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		* with an acceleration of A m/s^2, the acceleration value is equal to
	* A+9.81 which correspond to the acceleration of the		* A+9.81 which correspond to the acceleration of the device (+A m/s^2)
	* device (+A m/s^2) minus the force of gravity (-9.81 m/s^2).</li>		* 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>		* <h3>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
	* All values are in micro-Tesla (uT) and measure the ambient magnetic		* Sensor.TYPE_MAGNETIC_FIELD}:</h3>
	* field in the X, Y and Z axis.		* 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.		* <p>
	* In this case, the sensor should report its maxRange value in the "far" state and a value		* Note that some proximity sensors only support a binary "close" or "far"
	* less than maxRange in the "near" state.		* 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;		public final float[] values;

	/**		/**
	* The sensor that generated this event.		* The sensor that generated this event. See
	* See {@link android.hardware.SensorManager SensorManager}		* {@link android.hardware.SensorManager SensorManager} for details.
	* for details.
	*/		*/
	public Sensor sensor;		public Sensor sensor;

	/**		/**
	* The accuracy of this event.		* The accuracy of this event. See {@link android.hardware.SensorManager
	* See {@link android.hardware.SensorManager SensorManager}		* SensorManager} for details.
	* for details.
	*/		*/
	public int accuracy;		public int accuracy;

core/java/android/hardware/SensorManager.java

+378 −218

File changed.

Preview size limit exceeded, changes collapsed.