com.docomostar.device.location
クラス GyroSensor

Object
  com.docomostar.device.location.GyroSensor

public class GyroSensor
extends Object

[iアプリオプションAPI]

ジャイロセンサ機能を提供します。
ジャイロセンサ機能は、角速度を取得する機能を提供します。 計測データの種類については、GyroData クラスを参照して下さい。

計測を行うにはあらかじめ setEnabled(boolean) メソッドで ジャイロセンサ機能を有効化しておく必要があります。

角速度の計測方法としては、現在の角速度値を得るワンショット計測と、 周期的に連続して角速度値を得る周期計測を提供します。 周期計測では、実装内部の計測データ蓄積バッファに計測結果を蓄積します。 アプリケーションは周期計測中あるいは計測後に蓄積バッファ内の計測結果を取得できます。

計測結果は、GyroData オブジェクトを介して取得できます。 GyroData オブジェクトは ワンショット計測用、 周期計測(全データ)用、 周期計測(最新データ)用に各 1 つずつ生成され、 計測結果は各オブジェクトが保持する配列に格納されます。

周期計測中に、ワンショット計測、 周期計測開始を行うと例外が発生します。

周期計測中に Canvas の座標系を変更する(Canvas2 を使用する)場合、 蓄積バッファ内のデータの一貫性が保証されなくなるため、 Star アプリが期待する計測結果が得られない場合があります。 Star アプリが期待する結果を得るためには、 一度周期計測を停止した上で蓄積バッファからデータを取得してから、 Canvas の座標系を変更し、周期計測を再開して下さい。

導入されたバージョン:

Star-1.5

フィールドの概要

static int	ANGULAR_VELOCITY_X 計測データの種類を示す値で、X 軸回りの角速度を表します(=1)。
static int	ANGULAR_VELOCITY_Y 計測データの種類を示す値で、Y 軸回りの角速度を表します(=2)。
static int	ANGULAR_VELOCITY_Z 計測データの種類を示す値で、Z 軸回りの角速度を表します(=3)。

コンストラクタの概要

protected

GyroSensor() アプリケーションが直接このコンストラクタを呼び出して オブジェクトを生成することはできません。

メソッドの概要

void	disposeData() 周期計測用の蓄積バッファをクリアします。
int[]	getAvailableData() 実装がサポートしている計測データの種類を取得します。
GyroData	getCurrentData() 現在の角速度を計測し、結果を取得します(ワンショット計測)。
GyroData	getData() 周期計測用の蓄積データバッファから計測結果を取得します。
int	getDataSize() 周期計測用の蓄積データバッファに蓄積されているデータ数を取得します。
static GyroSensor	getGyroSensor() ジャイロセンサ機能のインスタンスを返します。
int	getIntervalResolution() 周期計測の計測間隔の解像度を取得します。
int	getMaxDataSize() 周期計測において実装内部で蓄積可能な最大データ数を取得します。
int	getMaxDataValue(int type) 計測データの最大値を取得します。
int	getMinDataValue(int type) 計測データの最小値を取得します。
GyroData	peekLatestData() 周期計測用の蓄積データバッファから最新の計測値を1つ取得します。
void	setEnabled(boolean enabled) ジャイロセンサ機能を有効化・無効化します。
void	start(int interval, boolean continuance) 周期計測を開始します。
void	stop() 周期計測を停止します。

クラス Object から継承されたメソッド

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

フィールドの詳細

ANGULAR_VELOCITY_X

public static final int ANGULAR_VELOCITY_X

計測データの種類を示す値で、X 軸回りの角速度を表します(=1)。

関連項目:

定数フィールド値

ANGULAR_VELOCITY_Y

public static final int ANGULAR_VELOCITY_Y

計測データの種類を示す値で、Y 軸回りの角速度を表します(=2)。

関連項目:

定数フィールド値

ANGULAR_VELOCITY_Z

public static final int ANGULAR_VELOCITY_Z

計測データの種類を示す値で、Z 軸回りの角速度を表します(=3)。

関連項目:

定数フィールド値

コンストラクタの詳細

GyroSensor

protected GyroSensor()

アプリケーションが直接このコンストラクタを呼び出して オブジェクトを生成することはできません。

メソッドの詳細

getGyroSensor

public static final GyroSensor getGyroSensor()

ジャイロセンサ機能のインスタンスを返します。
複数回呼び出された場合は、常に同じインスタンスを返します。 初期状態では、ジャイロセンサ機能は計測停止状態です。

実装によっては、ジャイロセンサ機能をサポートしていない場合があります。

戻り値:

ジャイロセンサ機能のインスタンスを返します。

例外:

UnsupportedOperationException -
ジャイロセンサ機能をサポートしていない場合に発生します。

DeviceException -
(NO_RESOURCES)
ジャイロセンサデバイスを確保できない場合に発生します。

getAvailableData

public int[] getAvailableData()

実装がサポートしている計測データの種類を取得します。
ANGULAR_VELOCITY_X、 ANGULAR_VELOCITY_Y、 ANGULAR_VELOCITY_Z のうち、 サポートする計測データの種類の値を含む配列を返します。

戻り値:

実装がサポートする計測データの種類を返します。 返される配列は、このオブジェクトが内部で保持している配列のコピーです。

getMinDataValue

public int getMinDataValue(int type)

計測データの最小値を取得します。
引数で指定された計測データが取り得る値の最小値を取得可能です。 計測データは、この最小値以上の値になります。

パラメータ:

type - 取得する計測データの種類を指定します。ANGULAR_VELOCITY_X、 ANGULAR_VELOCITY_Y、 ANGULAR_VELOCITY_Z のいずれかを指定します。

戻り値:

指定された計測データが取り得る値の最小値を返します。

例外:

IllegalArgumentException -
引数 type に不正な値、または実装がサポートしていない値を指定した場合に発生します。

getMaxDataValue

public int getMaxDataValue(int type)

計測データの最大値を取得します。
引数で指定された計測データが取り得る値の最大値を取得可能です。 計測データは、この最大値以下の値になります。

パラメータ:

type - 取得する計測データの種類を指定します。ANGULAR_VELOCITY_X、 ANGULAR_VELOCITY_Y、 ANGULAR_VELOCITY_Z のいずれかを指定します。

戻り値:

指定された計測データが取り得る値の最大値を返します。

例外:

IllegalArgumentException -
引数 type に不正な値、または実装がサポートしていない値を指定した場合に発生します。

getCurrentData

public GyroData getCurrentData()

現在の角速度を計測し、結果を取得します(ワンショット計測)。

GyroData オブジェクトが保持する配列の値を、 ワンショット計測結果で上書きします。 その後、この GyroData オブジェクトへの参照を返します。 常に同じオブジェクトへの参照を返します。 返されるオブジェクトは、 getData(), peekLatestData() とは異なります。

本メソッドの実行に成功すると、 周期計測用の計測結果蓄積バッファはクリアされます。

戻り値:

ワンショット計測結果を格納した GyroData オブジェクトを返します。

例外:

IllegalStateException -
ジャイロセンサ機能が無効化されている場合に発生します。

DeviceException -
(ILLEGAL_STATE)
周期計測中の場合に発生します。

start

public void start(int interval,
                  boolean continuance)

周期計測を開始します。指定した間隔毎に周期計測を行います。 実装がサポートしている計測間隔は、getIntervalResolution() で得られる解像度の倍数です。 実装サポート値以外の計測間隔を指定した場合、指定した値以上で最も実装サポート値に近い値が指定されたものとして扱われます。

周期計測中にアプリケーションがサスペンドした場合に、 周期計測を継続するかどうかを指定することができます。 引数 continuance に、周期計測を継続する場合は true、 周期計測を停止する場合は false を指定します。
サスペンド時に周期計測を停止する場合、周期計測を再開させるためにはレジューム処理において、 再度本メソッドを呼び出して下さい。 サスペンド前の計測値は getData()により取得して下さい。
端末がサスペンド発生時における周期計測の継続をサポートしていない場合、 引数 continuance に true を指定して本メソッドを呼び出すと、 UnsupportedOperationException が発生します。

計測結果は、実装内部の計測結果蓄積バッファに蓄積されていきます。 蓄積可能な最大データ数は、getMaxDataSize() により取得できます。 最大データ数を超えると、蓄積されたデータの古いものから上書きします。 計測結果は、 getData() により、周期計測中および周期計測後に取得できます。 蓄積された計測結果は、次にワンショット計測、周期計測を行った場合、また disposeData() 、 getData() を呼び出した場合、アプリケーションを終了した場合にクリアされます。

周期計測を停止させるためには、stop() メソッドを使用します。 サスペンド時に周期計測を継続している場合も含め、 アプリケーションが終了した場合、周期計測は停止します。 また、周期計測中にジャイロセンサ機能が無効化された場合、 周期計測は停止します。

getCurrentData() メソッド呼び出し中に 別のスレッドからこのメソッドが呼び出された場合、 getCurrentData() 呼び出し終了までこの メソッドの実行は遅延されます。

本メソッドの実行に成功すると、周期計測用の蓄積バッファはクリアされます。

パラメータ:

interval - 周期計測の間隔をミリ秒単位で指定します。

continuance - サスペンド時に周期計測を継続するかどうかを指定します。

例外:

UnsupportedOperationException -
サスペンド発生時における周期計測の継続をサポートしていない場合に発生します。

IllegalArgumentException -
引数 interval の値が 0 以下の場合に発生します。

IllegalStateException -
ジャイロセンサ機能が無効化されている場合に発生します。

DeviceException -
(ILLEGAL_STATE)
周期計測中の場合に発生します。

stop

public void stop()

周期計測を停止します。
周期計測中以外に呼ばれた場合、何もしません。

関連項目:

start(int, boolean)

getIntervalResolution

public int getIntervalResolution()

周期計測の計測間隔の解像度を取得します。
このメソッドにより得られる値の自然数倍の計測間隔をサポートします。

戻り値:

実装がサポートする周期計測間隔の解像度をミリ秒単位で返します。

関連項目:

start(int, boolean)

getMaxDataSize

public int getMaxDataSize()

周期計測において実装内部で蓄積可能な最大データ数を取得します。
周期計測は、最大データ数を超えると蓄積されたデータの古いものから上書きします。

戻り値:

実装がサポートする蓄積可能な最大データ数を返します。

関連項目:

start(int, boolean)

getDataSize

public int getDataSize()

周期計測用の蓄積データバッファに蓄積されているデータ数を取得します。

戻り値:

蓄積データ数を返します。

getData

public GyroData getData()

周期計測用の蓄積データバッファから計測結果を取得します。

GyroData オブジェクトが保持する配列の値を、蓄積バッファに蓄積されている全計測データで上書きします。 その後、この GyroData オブジェクトへの参照を返します。 常に同じオブジェクトへの参照を返します。 返されるオブジェクトは getCurrentData(), peekLatestData() とは異なります。

本メソッドの実行に成功すると、周期計測用の蓄積バッファはクリアされます。

蓄積バッファに計測データが 1 つも蓄積されていない時に本メソッドを呼び出した場合、 返される GyroData オブジェクトの計測データ数は 0 になります。

周期計測中に計測結果を取得した場合でも引き続き周期的に計測されます。

戻り値:

周期計測の全計測データを格納した GyroData オブジェクトを返します。

関連項目:

start(int, boolean)

peekLatestData

public GyroData peekLatestData()

周期計測用の蓄積データバッファから最新の計測値を1つ取得します。

GyroData オブジェクトが保持する配列の値を、 蓄積バッファに蓄積されている最新の計測データ 1 つで上書きします。 その後、この GyroData オブジェクトへの参照を返します。 常に同じオブジェクトへの参照を返します。 返されるオブジェクトは getData(), getCurrentData() とは異なります。

本メソッドの実行に成功しても、 周期計測用の蓄積バッファはクリアされません。

蓄積バッファに計測データが 1 つも蓄積されていない時に本メソッドを呼び出した場合、 返される GyroData オブジェクトの 計測データ数 は 0 になります。

戻り値:

周期計測の最新計測データ 1 つを格納した GyroData オブジェクトを返します。

disposeData

public void disposeData()

周期計測用の蓄積バッファをクリアします。

関連項目:

start(int, boolean)

setEnabled

public void setEnabled(boolean enabled)

ジャイロセンサ機能を有効化・無効化します。 角速度の計測を行うには、ジャイロセンサ機能を有効化する必要があります。

ジャイロセンサ機能が有効化されている間は、通常より多くの電力を消費します。 ジャイロセンサ機能を利用しないときは、このメソッドで無効化して下さい。

ジャイロセンサ機能が既に有効化されている状態で有効化しようとしたり、 既に無効化されている状態で無効化しようとした場合には、何もしません。

このメソッドでジャイロセンサ機能を無効化しても、 バッファに蓄積されているデータはクリアされません。

パラメータ:

enabled - ジャイロセンサ機能を有効化するには true を、 無効化するには false を、それぞれ指定します。