ゲーム コントローラ ライブラリを使用してゲーム コントローラのサポートをゲームに追加するには、以下の関数を使用します。
ゲーム コントローラ ライブラリの初期化と破棄
Paddleboat_init 関数を使用してゲーム コントローラ ライブラリを初期化します。
Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)
Paddleboat_init は 2 つのパラメータを取ります。
- 現在のスレッドにアタッチされた
JNIEnvへのポインタ。 Contextの派生クラスへのjobjectJNI オブジェクト参照。すべてのContext派生クラス オブジェクトは有効です（Activity、NativeActivity、GameActivityなどを含みますが、これらに限定されません）。
Paddleboat_init は、初期化が成功した場合に PADDLEBOAT_NO_ERROR を返し、それ以外の場合は相当するエラーコードを返します。
Paddleboat_isInitialized を使用すると、ゲーム コントローラ ライブラリが正常に初期化されたかどうかを確認できます。これはブール値を返します。true の場合、API を使用できます。
bool Paddleboat_isInitialized()
アプリケーションを終了する前には、Paddleboat_destroy 関数を使用してゲーム コントローラ ライブラリをシャットダウンします。この関数は単一のパラメータを受け取ります。現在のスレッドにアタッチされた JNIEnv へのポインタです。Paddleboat_init は、Paddleboat_destroy の後に再度呼び出すことができます。
void Paddleboat_destroy(JNIEnv *env)
ライフサイクル イベントをライブラリに通知する
ゲーム コントローラ ライブラリに、アクティビティのライフサイクル onStop イベントと onStart イベントを通知する必要があります。停止と開始のイベントを処理するコードから、Paddleboat_onStop 関数と Paddleboat_onStart 関数を呼び出します。どちらの関数も、現在のスレッドにアタッチされた JNIEnv へのポインタを 1 つ取ります。
void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)
コントローラのステータスのコールバックを登録または削除する
ゲーム コントローラ ライブラリは、コントローラが接続または接続解除されたときに、コントローラ ステータス コールバックを使用してゲームに通知します。一度にサポートされるコントローラ ステータス コールバックは 1 つだけです。
- コントローラ ステータス コールバックを登録するか、以前登録したコールバックを新しいコールバック関数に置き換えるには、
Paddleboat_setControllerStatusCallback関数を呼び出します。 - 現在登録されているコールバックを削除するには、
NULLまたはnullptrを渡します。 userDataパラメータは、ユーザー定義データへのポインタです（省略可能）。userDataパラメータはコールバック関数に渡されます。このポインタは、後続のPaddleboat_setControllerStatusCallback呼び出しによって変更されるまで内部的に保持されます。
void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
statusCallback, void *userData)
コールバック関数の関数シグネチャを次に示します。
typedef void (*Paddleboat_ControllerStatusCallback)(
const int32_t controllerIndex,
const Paddleboat_ControllerStatus controllerStatus,
void *userData)
| パラメータ | 説明 |
|---|---|
controllerIndex
|
コールバックを開始したコントローラのインデックス。0 から PADDLEBOAT_MAX_CONTROLLERS - 1 の値になります。 |
controllerStatus
|
PADDLEBOAT_CONTROLLER_JUST_CONNECTED または PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED の列挙値。 |
userData
|
最後の Paddleboat_setControllerStatusCallback 呼び出しで指定されたユーザー定義データへの省略可能なポインタ（NULL を指定可能）。 |
ゲーム コントローラ ライブラリの更新関数を呼び出す
ゲーム コントローラ ライブラリの更新関数 Paddleboat_update は、ゲームフレームごとに 1 回（できればフレームの開始付近で）呼び出す必要があります。この関数は、単一のパラメータ（現在のスレッドにアタッチされている JNIEnv へのポインタ）を受け取ります。
void Paddleboat_update(JNIEnv *env)
イベントの処理
入力イベントを受け取ったら、検査のためにそれをゲーム コントローラ ライブラリに転送する必要があります。ゲーム コントローラ ライブラリは、入力イベントが管理対象のデバイスのいずれかに関連付けられているかどうかを評価します。管理対象のデバイスからのイベントが処理され、使用されます。
ゲーム コントローラ ライブラリは、2 種類の入力イベント AInputEvents と GameActivity をサポートしています。
AInputEvent の処理
イベント処理コードから Paddleboat_processInputEvent を呼び出して AInputEvents を転送する必要があります。
int32_t Paddleboat_processInputEvent(const AInputEvent *event)
Paddleboat_processInputEvent は、イベントが無視された場合は 0 を返し、ゲーム コントローラ ライブラリに処理されて使用された場合は 1 を返します。
GameActivity のイベント処理
ゲームで GameActivity を使用している場合は、イベント処理コードから Paddleboat_processGameActivityKeyInputEvent または Paddleboat_processGameActivityMotionInputEvent を呼び出して、GameActivityKeyEvent イベントと GameActivityMotionEvent イベントを転送します。
int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
const size_t eventSize)
| パラメータ | 説明 |
|---|---|
event
|
GameActivityKeyEvent 構造体または GameActivityMotionEvent 構造体へのポインタ（どちらなのかは呼び出される関数による）。 |
eventSize
|
event パラメータで渡されたイベント構造体のサイズ（バイト単位）。 |
どちらの関数も、イベントが無視された場合は 0 を返し、ゲーム コントローラ ライブラリによってイベントが処理されて使用された場合は 1 を返します。
GameActivity では、GameActivityPointerAxes_enableAxis 関数を使用して、有効なモーション軸を指定する必要があります。Paddleboat_getActiveAxisMask の呼び出しは、接続されているコントローラで使用される、現在アクティブなモーション軸のビットマスクを返します。
uint64_t Paddleboat_getActiveAxisMask()
この処理方法の例については、GameActivity を使用するゲーム コントローラ ライブラリのサンプルをご覧ください。このサンプルは、アクティブな軸マスクをポーリングし、新しい軸が使用されると GameActivity に通知します。これは NativeEngine::CheckForNewAxis() 関数で実装されています。
void NativeEngine::CheckForNewAxis() {
// Tell GameActivity about any new axis ids so it reports
// their events
const uint64_t activeAxisIds = Paddleboat_getActiveAxisMask();
uint64_t newAxisIds = activeAxisIds ^ mActiveAxisIds;
if (newAxisIds != 0) {
mActiveAxisIds = activeAxisIds;
int32_t currentAxisId = 0;
while(newAxisIds != 0) {
if ((newAxisIds & 1) != 0) {
LOGD("Enable Axis: %d", currentAxisId);
GameActivityPointerAxes_enableAxis(currentAxisId);
}
++currentAxisId;
newAxisIds >>= 1;
}
}
}
コントローラの読み取り
ゲーム コントローラ ライブラリは、インデックス値を使用して特定のコントローラを参照します。有効なインデックス値の範囲は 0 から PADDLEBOAT_MAX_CONTROLLERS - 1 までです。Paddleboat_getControllerStatus 関数は、指定されたコントローラ インデックスのステータスを判断します。
Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
const int32_t controllerIndex)
接続されているコントローラから情報を読み取るための関数は 3 つあります。
Paddleboat_getControllerName関数は、コントローラ デバイスの名前を取得します。Paddleboat_getControllerInfo関数は、コントローラ デバイス自体に関するデータを取得します。Paddleboat_getControllerData関数は、コントローラ入力の現在の状態を取得します。
コントローラ名
Paddleboat_getControllerName function は、コントローラ インデックス、バッファサイズの 2 つの入力パラメータと、コントローラ名文字列を格納するバッファへのポインタを取ります。名前文字列は、UTF-8 エンコードを使用した C 文字列の形式になります。デバイスの名前は、InputDevice.getName() を使用して内部で取得されます。
Paddleboat_getControllerName が名前を正常に取得すると、PADDLEBOAT_NO_ERROR が返されます。それ以外の場合は、相当するエラーコードが返されます。
Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
const size_t bufferSize,
char *controllerName);
| パラメータ | 説明 |
|---|---|
controllerIndex
|
コールバックを開始したコントローラのインデックス。0 から PADDLEBOAT_MAX_CONTROLLERS - 1 の値になります。 |
bufferSize
|
controllerName によって渡されるバッファのサイズ（バイト単位）。必要に応じて、バッファに収まるように文字列が切り詰められます。 |
controllerName
|
コントローラ名を格納する、bufferSize バイトのバッファへのポインタ。名前は、UTF-8 エンコードを使用した C 文字列で格納されます。 |
コントローラ デバイスの情報
Paddleboat_getControllerInfo function は、コントローラ インデックスと Paddleboat_Controller_Info 構造体へのポインタという 2 つの入力パラメータを取ります。
Paddleboat_Controller_Info にデータが正常に格納された場合、Paddleboat_getControllerInfo から PADDLEBOAT_NO_ERROR が返されます。それ以外の場合は、相当するエラーコードが返されます。
Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
Paddleboat_Controller_Info *controllerInfo)
Paddleboat_Controller_Info 構造には、コントローラに関するデバイス固有の情報が含まれます。
typedef struct Paddleboat_Controller_Info {
uint32_t controllerFlags;
int32_t controllerNumber;
int32_t vendorId;
int32_t productId;
int32_t deviceId;
Paddleboat_Controller_Thumbstick_Precision leftStickPrecision;
Paddleboat_Controller_Thumbstick_Precision rightStickPrecision;
} Paddleboat_Controller_Info;
typedef struct Paddleboat_Controller_Thumbstick_Precision {
float stickFlatX;
float stickFlatY;
float stickFuzzX;
float stickFuzzY;
} Paddleboat_Controller_Thumbstick_Precision;
一部の構造体メンバーには、コントローラに関連付けられた InputDevice から取得した値が設定されます。
controllerNumber - InputDevice.getControllerNumber()
vendorId - InputDevice.getVendorId()
productId - InputDevice.getProductId()
deviceId - InputDevice.getId()
stickFlat値は、中央のフラットな位置の範囲を表します。この値は、主にセルフセンタリング型デバイスのデフォルトの中央「デッドゾーン」を算出する場合に便利です。stickFuzz値は、エラー許容値です。つまり、ノイズやデバイス感度の制限によって現在の値が実際の値からどの程度外れる可能性があるかを表します。
どちらの値も、各ディメンションの最大軸値 1.0 に正規化されます。
controllerFlags メンバーには、個別にビットマスクされたフラグと複数ビットを組み合わせた値とをさらに組み合わせものが含まれます。
controllerFlags と PADDLEBOAT_CONTROLLER_LAYOUT_MASK の論理 AND を計算すると、Paddleboat_ControllerButtonLayout 列挙値にキャストできる値になります。この列挙値は、コントローラで使用されるボタンのアイコン画像とレイアウトを指定します。
enum Paddleboat_ControllerButtonLayout {
// Y
// X B
// A
PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD = 0,
// △
// □ ○
// x
PADDLEBOAT_CONTROLLER_LAYOUT_SHAPES = 1,
// X
// Y A
// B
PADDLEBOAT_CONTROLLER_LAYOUT_REVERSE = 2,
// X Y R1 L1
// A B R2 L2
PADDLEBOAT_CONTROLLER_LAYOUT_ARCADE_STICK = 3,
PADDLEBOAT_CONTROLLER_LAYOUT_MASK = 3
};
以下の定数は、機能ビットを定義します。コントローラが特定の機能をサポートしているかどうかを確認するには、対応する定数の論理 AND を controllerFlags に適用します。結果が 0 以外の場合は、その機能がコントローラでサポートされていることを意味します。
PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD
このフラグビットを設定した場合、コントローラにはタッチパッドが統合されています。タッチパッドが押されると、コントローラは Paddleboat_Controller_Data.buttonsDown フィールドの PADDLEBOAT_BUTTON_TOUCHPAD ビットを設定します。
PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE
このフラグビットが設定されている場合、コントローラはポインティング デバイスをエミュレートします。Paddleboat_Controller_Data 構造体の virtualPointer メンバーには、仮想ポインタの現在の座標が設定されます。
コントローラのデータ
Paddleboat_getControllerData 関数は、コントローラ インデックスと Paddleboat_Controller_Data 構造体へのポインタという 2 つの入力パラメータを取ります。Paddleboat_Controller_Data にデータが正常に入力されると、Paddleboat_getControllerInfo は PADDLEBOAT_NO_ERROR を返します。それ以外の場合は、適切なエラーコードが返されます。
Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
Paddleboat_Controller_Data *controllerData)
Paddleboat_Controller_Data 構造体には、コントローラの現在のコントロール入力値が含まれています。
typedef struct Paddleboat_Controller_Data {
uint64_t timestamp;
uint32_t buttonsDown;
Paddleboat_Controller_Thumbstick leftStick;
Paddleboat_Controller_Thumbstick rightStick;
float triggerL1;
float triggerL2;
float triggerR1;
float triggerR2;
Paddleboat_Controller_Pointer virtualPointer;
} Paddleboat_Controller_Data;
typedef struct Paddleboat_Controller_Pointer {
float pointerX;
float pointerY;
} Paddleboat_Controller_Pointer;
typedef struct Paddleboat_Controller_Thumbstick {
float stickX;
float stickY;
} Paddleboat_Controller_Thumbstick;
値の範囲
| 入力タイプ | 値の範囲 |
|---|---|
| サムスティック軸 | -1.0～1.0 |
| トリガー | 0.0 から 1.0 まで |
| 仮想ポインタ | 0.0 からウィンドウの幅 / 高さまで（ピクセル単位） |
構造体の詳細
| 構造体メンバー | 説明 |
|---|---|
buttonsDown
|
各ボタンに 1 ビットのビットフィールドの配列。ボタンのビットマスク定数は、paddleboat.h ヘッダー ファイルで定義され、PADDLEBOAT_BUTTON_ で始まります。 |
timestamp.
|
最新のコントローラ入力イベントのタイムスタンプ。タイムスタンプはエポックからのマイクロ秒数です。 |
virtualPointer
|
仮想ポインタの位置。controllerFlags に PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE フラグが設定されている場合にのみ有効です。それ以外の場合、0.0, 0.0 になります。 |