ch.aplu.android

Class GGComboSensor

java.lang.Object

ch.aplu.android.GGComboSensor

public class GGComboSensor
extends java.lang.Object

Singleton abstraction of the hardware combo sensor (acceleration, gravitation (magnetic field), orientation). The sensor is polled by a system internal thread using a certain polling delay defined in class SensorManager (default SensorManager.SENSOR_DELAY_NORMAL). The measured values are stored and reported by the GGComboSensor polling methods getOrientation(), getAcceleration(), getMagneticField(). Both raw values (the sensor is considered to be in fixed position relative to the device) or adpated values (depending on the current screen orientation of the application, 4 rotations: portrait,landscape, reverse portrait, reverse landscape are supported) are returned.

The coordinate system fixed with the device is carthesian and the axes are oriented as usual in mathematics: x-axes to the right, y-axes upwards and z-axes perpenticular (right-hand helix). It may or may not be rotated when the application window changes the orientation.

This class uses the older (deprecated) Android sensor API which may deliver more accurate values for the magnetic field and thus for the calculated orientation (especially for the azimuth) when used with older Android devices. For newer devices you may use the GGSensor class that is based on the new Android sensor API, but this class also works on newer devices.

Method Summary

Methods

Modifier and Type	Method and Description
void	addComboSensorListener(GGComboSensorListener listener) Registers a GGComboSensorListener to get notifications when the sensor reports new values.
float[]	getAcceleration(int precision) Returns the current acceleration components.
float[]	getMagneticField(int precision) Returns the current magnetic field components.
float[]	getOrientation(int precision) Returns the current orientation angles (azimuth, pitch, roll).
static GGComboSensor	init(android.app.Activity activity) Initializes the combo sensor for the given activity and returns a GGComboSensor reference for the given activity.
static GGComboSensor	init(android.app.Activity activity, int sensorDelay) Initializes the orientation sensor for the given activity and returns a GGComboSensor reference for the given activity.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

init

public static GGComboSensor init(android.app.Activity activity)

Initializes the combo sensor for the given activity and returns a GGComboSensor reference for the given activity. If the combo sensor was enabled before, releases the old resources. The sensor is polled with the standard delay SensorManager.SENSOR_DELAY_NORMAL (about 100 ms period).

Returns:

a GGComboSensor reference to get access to polling methods

init

public static GGComboSensor init(android.app.Activity activity,
                 int sensorDelay)

Initializes the orientation sensor for the given activity and returns a GGComboSensor reference for the given activity. If the combo sensor was enabled before, releases the old resources. The sensor is polled with the given sensorDelay (constant in the SensorManager class).

Parameters:

activity - the activity used to access the system

sensorDelay - one of the SENSOR_DELAY constants in class SensorManager

Returns:

a GGComboSensor reference to get access to polling methods

getOrientation

public float[] getOrientation(int precision)

Returns the current orientation angles (azimuth, pitch, roll). If the orientation sensor is not installed, all components are zero. Use GameGrid.enumerateSensors() to check if the orientation sensor is available.

Thread.sleep(1) is included to release the thread when polling in a narrow loop.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

pitch is positive, when the y-axes points downwards
roll is positive, when the x-axes points downwards

Be aware that due to sensor noise, the value may jitter.

Parameters:

precision - the number of fractional digits to report to eliminate sensor jitter (0..5).

Returns:

the mesured components (degrees)
index 0,1,2: azimuth, pitch, roll in the device fixed coordinate system
index 3,4,5: values adapted to current device orientation

getAcceleration

public float[] getAcceleration(int precision)

Returns the current acceleration components. If the acceleration sensor is not installed, all components are zero. Use GameGrid.enumerateSensors() to check if the acceleration sensor is available.

Thread.sleep(1) is included to release the thread when polling in a narrow loop.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

The returned acceleration is the current acceleration minus the earth gravitational acceleration:
values[0]: Device acceleration minus gx on the x-axis
values[1]: Device acceleration minus gy on the y-axis
values[2]: Device acceleration minus gz on the z-axis

Example: Device on a horizontal table: gx = 0, gy = 0 and gz = -9.81; reported values: {0, 0, +9.81}

Be aware that due to sensor noise, the value may jitter.

Parameters:

precision - the number of fractional digits to report to eliminate sensor jitter (0..5).

Returns:

the mesured components (m/s^2)
index 0,1,2: ax, ay, az in the device fixed coordinate system
index 3,4,5: values adapted to current device orientation

getMagneticField

public float[] getMagneticField(int precision)

Returns the current magnetic field components. If the magnetic field sensor is not installed, all components are zero. Use GameGrid.enumerateSensors() to check if the magnetic sensor is available.

Thread.sleep(1) is included to release the thread when polling in a narrow loop.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

Be aware that due to sensor noise, the value may jitter.

Parameters:

precision - the number of fractional digits to report to eliminate sensor jitter (0..5).

Returns:

the mesured components (Microtesla (uT))
index 0,1,2: Bx, By, Bz in the device fixed coordinate system
index 3,4,5: values adapted to current device orientation

addComboSensorListener

public void addComboSensorListener(GGComboSensorListener listener)

Registers a GGComboSensorListener to get notifications when the sensor reports new values.

Parameters:

listener - the GGComboSensorListener to register