net.rim.device.api.system
Class AccelerometerData

java.lang.Object
  net.rim.device.api.system.AccelerometerData

public class AccelerometerData
extends Object

Encapsulates accelerometer sensor readings. Contains some or all of the following acceleration information:

• Orientation, which represents handheld orientation with respect to the ground, for example, AccelerometerSensor.ORIENTATION_TOP_UP or AccelerometerSensor.ORIENTATION_LEFT_UP.
• Raw acceleration samples, which are vectors of three coordinates: X, Y, and Z. Each raw value represents acceleration along X, Y and Z axes.
• Raw samples history, which are buffered samples that are allocated based on samples count. The buffers returned by AccelerometerData.getXAccHistory(), AccelerometerData.getYAccHistory() and AccelerometerData.getZAccHistory() have the most recent acceleration value stored at index 0, while the oldest value is stored at the end of the array.

NOTE: For information on how accelerometer sensor readings are calculated, see AccelerometerSensor.

The data object is populated based on the channel configuration (see AccelerometerChannelConfig). For example, if an application is only interested in orientation information, raw acceleration sample values are not provided.

See Also:

AccelerometerChannelConfig

Since:

BlackBerry API 4.7.0

Method Summary
long	getLastTimestamp() Returns the timestamp for the last raw acceleration measurement.
short	getLastXAcceleration() Returns the latest acceleration along X axis.
short	getLastYAcceleration() Returns the latest acceleration along Y axis.
short	getLastZAcceleration() Returns the latest acceleration along Z axis.
int	getNewBatchLength() Returns count of the new samples in the historical array since the last query call.
int	getOrientation() Returns the last known orientation of the handheld.
long[]	getSampleTsHistory() Returns sample timings.
short[]	getXAccHistory() Returns historical readings for acceleration along the X axis.
short[]	getYAccHistory() Returns historical readings for acceleration along the Y axis.
short[]	getZAccHistory() Returns historical readings for acceleration along the Z axis.

Methods inherited from class java.lang.Object

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

Method Detail

getLastXAcceleration

public short getLastXAcceleration()
                           throws NullPointerException

Returns the latest acceleration along X axis. This method is only applicable if data is retrieved from a channel configured for raw acceleration; otherwise garbage data may be returned.

Returns:

Latest acceleration along X axis.

Throws:

NullPointerException - if the data is retrieved from orientation only channel, resulting in no raw sample buffers being allocated.

Since:

BlackBerry API 4.7.0

getLastYAcceleration

public short getLastYAcceleration()
                           throws NullPointerException

Returns the latest acceleration along Y axis. This method is only applicable if data is retrieved from a channel configured for raw acceleration; otherwise garbage data may be returned.

Returns:

Latest acceleration along Y axis.

Throws:

NullPointerException - if the data is retrieved from orientation only channel, resulting in no raw sample buffers being allocated.

Since:

BlackBerry API 4.7.0

getLastZAcceleration

public short getLastZAcceleration()
                           throws NullPointerException

Returns the latest acceleration along Z axis. This method is only applicable if data is retrieved from a channel configured for raw acceleration; otherwise garbage data may be returned.

Returns:

Latest acceleration along Z axis.

Throws:

NullPointerException - if the data is retrieved from orientation only channel resulting in no raw sample buffers being allocated.

Since:

BlackBerry API 4.7.0

getLastTimestamp

public long getLastTimestamp()
                      throws NullPointerException

Returns the timestamp for the last raw acceleration measurement. This method is only applicable if data is retrieved from a channel configured for raw acceleration; otherwise garbage data may be returned.

Returns:

Time (in milliseconds).

Throws:

NullPointerException - if the data is retrieved from orientation only channel, resulting in no raw sample buffers being allocated.

Since:

BlackBerry API 4.7.0

getOrientation

public int getOrientation()

Returns the last known orientation of the handheld. If the channel is opened for raw data only, the returning value is -1.

Returns:

One of the ORIENTATION_XXX constants from AccelerometerSensor class if queried; -1 otherwise

See Also:

AccelerometerSensor

Since:

BlackBerry API 4.7.0

getXAccHistory

public short[] getXAccHistory()

Returns historical readings for acceleration along the X axis. The most recent sample is stored at the index 0. The new batch of samples are stored in [0..NewBatchLength] elements.

Returns:

X axis historical sample buffer, if allocated; null otherwise.

Since:

BlackBerry API 4.7.0

getYAccHistory

public short[] getYAccHistory()

Returns historical readings for acceleration along the Y axis. The most recent sample is stored at the index 0. The new batch of samples are stored in [0..NewBatchLength] elements.

Returns:

Y axis historical sample buffer, if allocated; null otherwise.

Since:

BlackBerry API 4.7.0

getZAccHistory

public short[] getZAccHistory()

Returns historical readings for acceleration along the Z axis. The most recent sample is stored at the index 0. The new batch of samples are stored in [0..NewBatchLength] elements.

Returns:

Z axis historical sample buffer if was allocated, null otherwise.

Since:

BlackBerry API 4.7.0

getSampleTsHistory

public long[] getSampleTsHistory()

Returns sample timings. The returned array corresponds to the X, Y, and Z samples history. Each array element contains a timestamp (in milliseconds) when the corresponding acceleration value was sampled.

Returns:

an array with timestamps in milliseconds that corresponds to the X, Y and Z raw data if the array was allocated; null otherwise.

Since:

BlackBerry API 4.7.0

getNewBatchLength

public int getNewBatchLength()

Returns count of the new samples in the historical array since the last query call.

Returns:

value from 0 up to buffer length

Since:

BlackBerry API 4.7.0