Adobe AIR の GameInput クラス

基本的な使い方は、GameInput から、接続されている GameInputDevice を取得、GameInputDevice から内蔵されている GameInputControl を取得。GameInputControl から操作状況を取得、です。

今のところ Android 4.1 以降のみで利用が可能とされています。

GameInput クラス

GameInput は、ゲーム操作のための、入力デバイスを管理するクラスです。静的な属性を 2 つ持っています。

GameInput.isSupported: Boolean
GameInput.numDevices: int

それぞれ GameInput 関連の API の利用可否と、接続されたデバイスの数を知ることができます。どちらも読み取り専用です。

接続されているデバイスを取得するには getDeviceAt() メソッドを使います。静的な関数で、引数は、利用可能な入力デバイスごとに割り振られているインデックスです。例えば以下のように使います。

var myDevice:GameInputDevice;
if (GameInput.numDevices > 0)
{
  myDevice = GameInput.getDeviceAt(0);
}

ところで、ゲームの起動後に、入力デバイスの電源がオン／オフされる場合もあるかもしれません。そこで、利用可能な入力デバイスの追加や削除が起こると、GameInputEvent イベントが発生するようになっています。

これらのイベントを取得するには、下のように GameInput のインスタンスにイベントリスナを追加します。

var myGameInput:GameInput;
myGameInput = new GameInput();
// ゲーム入力デバイスが追加されたときに呼ばれるリスナ関数を追加
myGameInput.addEventListener(GameInputEvent.DEVICE_ADDED, onAdded);
// ゲーム入力デバイスが削除されたときに呼ばれるリスナ関数を追加
myGameInput.addEventListener(GameInputEvent.DEVICE_REMOVED, onRemoved);
 
function onAdded(e:GameInputEvent):void
{
  trace("ゲーム入力機器が追加されました " + e.device);
}
function onRemoved(e:GameInputEvent):void
{
  trace("ゲーム入力機器が削除されました "+ e.device);
}

イベントリスナには、引数として GameInputEvent のインスタンスが渡されます。GameInputEvent インスタンスからは、追加または削除されたデバイスの情報を取得できます。使用する属性名は device で、属性の型は GameInputDevice です。

予期せず入力デバイスがオフになったため再接続したという場合、オフになる前の状態のままでは、正しく入力デバイスが利用できないケースもありそうです。入力デバイス削除のイベント処理は、忘れないようにしましょう。

GameInputDevice クラス

GameInputDevice クラスは、個々の入力デバイスを扱うためのクラスです。入力デバイスの接続状況に応じて、インスタンスが生成／削除されます。

デバイスは、デフォルトでは利用不可の状態になっているため、利用する前に enabled 属性の値を true にします。

myDevice.enabled = true;

GameInputDevice オブジェクトは、入力デバイスの情報を示す属性を持っています。いずれも読み取り専用の属性です。

id : String
name : String
numControls : int

id と name は、入力デバイスの製造元が決めた文字列です。両者を組み合わせると、個々の入力デバイスの判別に使用できます。

（getDeviceAt() などで使うインデックスの値は、入力デバイスの追加などによりシャッフルされるそうなので、デバイスの識別には使用しないほうが良さそうです）

入力デバイスには、複数のコントローラーが存在するかもしれません。numControls が示す数だけ getControlAt() メソッドを呼べば、全てのコントローラーに対応する GameInputControl のインスタンスを取得できます。

for (var i:int=0; i < myDevice.numControls; i++)
{
  var myControl:GameInputControl = myDevice.getControlAt(i);
}

GameInputControl クラス

GameInputControl のインスタンスからは、各コントローラーの状態を取得できます。以下の 5 つの属性を持っています。全て読み取り専用です。

device : GameInputDevice
id : String
minValue : Number
maxValue : Number
value : Number

device 属性はコントローラーを含む入力デバイスを表す GameInputDevice オブジェクトです。id 属性は、入力デバイス内で固有な識別名です。

minValue と maxValue は、それぞれコントローラーが返す可能性があるの最小値と最大値です。

最後の value が、コントローラーの現在の値になるわけですが、参照されるたびに直接コントローラーから取得しているわけではありません。代わりに、最後にコントローラーの値としてサンプリングされた値を返します。

サンプリングの間隔は、コントローラーではなく、入力デバイスに設定することになっていて、 GameInputDevice オブジェクトの sampleInterval にミリ秒単位で指定します。

sampleInterval のデフォルト値は 0 です。これは、フレーム毎に 1 回という指定になります。

GameInputControl には、サンプリングされた値が変わると、イベントとして通知する機能があります。イベントの取得方法は以下のような感じになります。

if (myDevice.numControls > 0)
{
  var myControl:GameInputControl = myDevice.getControlAt(0);
  myControl.addEventListener(Event.CHANGE, onChange);
}
 
function onChange(e:Event):void
{
  var control:GameInputControl = e.target as GameInputControl;
  var myVal:Number = control.value;
  // 以下、必要な処理を記述
}

sampleInterval の値を 0 より大きくすると、フレームレートよりも短い間隔でサンプリングが行われます。ただし、change イベントは、フレーム毎に 1 回しか呼ばれませんので、上の方法では、サンプリングされた全ての値を取得することはできません。

コントローラーの値のキャッシュ

そのような場合、最新の値以外も取得できるように、GameInputDevice クラスには、サンプリングされた値をキャッシュする機能が提供されています。

以下は GameInputDevice クラスのキャッシュ機能関連のメソッドです。

startCachingSamples(numSamples:int, controls:Vector.<String>):void
getCachedSamples(data:ByteArray, append:Boolean = false):int
stopCachingSamples():void

キャッシュに値を書き始めるように指示を出すのが startCachingSamples() メソッドです。最初の引数は、取得したいサンプル数の最大値です。

次の引数は、サンプル取得の対象となるコントローラーの ID のベクターです。サンプルに書き出される値は、このベクターに指定された順になります。

キャッシュできるデータの最大値はあらかじめ決められています。

public static const MAX_BUFFER_SIZE:int = 32000

これを超えるデータをキャッシュするように要求すると IOError が発生します。

キャッシュしたサンプルの取得は getCachedSamples() メソッドを使います。最初の引数はデータコピー用の ByteArray オブジェクトで、次の引数にデータを上書きするか、後ろに付け足すかを指定します。

メソッドの戻り値は、ByteArray に書き出されたサンプルの数です。ByteArray 内には古いデータから時系列にサンプルがコピーされます。

ByteArray にコピーされたサンプルは、キャッシュ用のバッファからは削除されます。

サンプルのキャッシュ書き出しを止めるには stopCachingSamples() メソッドを使います。このメソッドを呼ぶと、最新のサンプリングの値のみが利用できる状態になります。