ゲーム コントローラ ライブラリの使用

ゲーム コントローラ ライブラリを使用してゲーム コントローラのサポートをゲームに追加するには、以下の関数を使用します。

ゲーム コントローラ ライブラリの初期化と破棄

Paddleboat_init 関数を使用してゲーム コントローラ ライブラリを初期化します。

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init は 2 つのパラメータを取ります。

• 現在のスレッドにアタッチされた JNIEnv へのポインタ。
• Context の派生クラスへの jobject JNI オブジェクト参照。Context の派生クラスのオブジェクトはすべて有効です（Activity、NativeActivity、GameActivity など）。

Paddleboat_init は、初期化が成功した場合に PADDLEBOAT_NO_ERROR を返し、それ以外の場合は相当するエラーコードを返します。

Paddleboat_isInitialized を使用すると、ゲーム コントローラ ライブラリが正常に初期化されたかどうかを確認できます。これはブール値を返します。true の場合、API を使用できます。

bool Paddleboat_isInitialized()

アプリケーションを終了する前には、Paddleboat_destroy 関数を使用してゲーム コントローラ ライブラリをシャットダウンします。この関数は単一のパラメータを受け取ります。現在のスレッドにアタッチされた JNIEnv へのポインタです。Paddleboat_destroy の後に Paddleboat_init を再度呼び出しても構いません。

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)

ゲーム コントローラ ライブラリの更新関数を呼び出す

ゲーム コントローラ ライブラリの更新関数 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)

どちらの関数も、イベントが無視された場合は 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);

コントローラ デバイスの情報

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;

値の範囲

構造体の詳細