Gamecontroller-Bibliothek verwenden

Verwende die folgenden Funktionen, um Controller-Unterstützung zu deinem Spiel hinzuzufügen: die Game Controller-Bibliothek.

Game Controller-Bibliothek initialisieren und löschen

Verwenden Sie den Paddleboat_init. zum Initialisieren der Game Controller-Bibliothek.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init verwendet zwei Parameter:

• Ein Zeiger auf ein JNIEnv an den aktuellen Thread angehängt
• Ein jobject-JNI-Objektverweis auf einen Context abgeleitete Klasse. Beliebige Context abgeleitetes Klassenobjekt gültig ist, einschließlich, aber nicht beschränkt auf Activity, NativeActivity, oder GameActivity.

Paddleboat_init Rückgaberecht PADDLEBOAT_NO_ERROR, wenn die Initialisierung erfolgreich war, andernfalls ein entsprechender Fehlercode zurückgegeben.

Mit Paddleboat_isInitialized können Sie prüfen, ob das Spiel Controller-Bibliothek wurde initialisiert. Sie gibt einen booleschen Wert Wert. Falls wahr, kann die API verwendet werden.

bool Paddleboat_isInitialized()

Verwenden Sie vor Beendigung der Anwendung die Paddleboat_destroy um die Game Controller-Bibliothek herunterzufahren. Die Funktion nimmt eine einzelne -Parameter, ein Zeiger auf ein JNIEnv, das mit dem aktuellen Thread verknüpft ist. Paddleboat_init kann nach dem Paddleboat_destroy wieder aufgerufen werden.

void Paddleboat_destroy(JNIEnv *env)

Bibliothek von Lifecycle-Events informieren

Die Game Controller-Bibliothek muss über Aktivitätslebenszyklus onStop und onStart-Ereignisse. Rufen Sie die Methode Paddleboat_onStop und Paddleboat_onStart über den Code für die Verarbeitung von Stopp- und Start-Ereignissen. Beide Funktionen benötigen eine Einzelner Parameter: ein Zeiger auf ein JNIEnv, das mit dem aktuellen Thread verknüpft ist

void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)

Callback für den Controllerstatus registrieren oder entfernen

Die Game Controller-Mediathek verwendet einen Controller-Status-Callback, um ein Spiel zu benachrichtigen Ein Controller wird verbunden oder getrennt. Es wird nur ein Controller unterstützt Status-Callback zu ändern.

• Um einen Controller-Status-Callback zu registrieren oder einen zuvor erhaltenen Callback zu ersetzen registrierter Callback mit einer neuen Callback-Funktion die Funktion Paddleboat_setControllerStatusCallback-Funktion.
• Wenn du einen derzeit registrierten Callback entfernen möchtest, übergib NULL oder nullptr.
• Der Parameter userData ist ein optionaler Zeiger auf benutzerdefinierte Daten. Die Der Parameter userData wird an die Callback-Funktion übergeben. Dieser Zeiger wird intern beibehalten, bis sie durch einen nachfolgenden Aufruf von geändert wird. Paddleboat_setControllerStatusCallback

void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

Die Funktionssignatur der Callback-Funktion lautet:

typedef void (*Paddleboat_ControllerStatusCallback)(
  const int32_t controllerIndex,
  const Paddleboat_ControllerStatus controllerStatus,
  void *userData)

Parameter	Beschreibung
controllerIndex	Index des Controllers, der den Callback des Nutzers an. Ist ein Wert zwischen 0 und PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus	Enum-Wert von PADDLEBOAT_CONTROLLER_JUST_CONNECTED oder PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED
userData	Ein optionaler Zeiger (kann NULL sein) für den Nutzer die beim letzten Aufruf von Paddleboat_setControllerStatusCallback

Funktion zum Aktualisieren der Game Controller-Bibliothek aufrufen

Die Funktion zum Aktualisieren der Game Controller-Bibliothek Paddleboat_update sollte einmal pro Spiel-Frame aufgerufen werden, vorzugsweise nahe am Anfang des Frames. Die Funktion verwendet einen einzelnen Parameter, einen Zeiger auf ein JNIEnv, das an die aktuellen Thread.

void Paddleboat_update(JNIEnv *env)

Ereignisse verarbeiten

Wenn du Eingabeereignisse erhältst, muss dein Spiel zur Überprüfung an die Game Controller-Bibliothek weiterleiten. Gamecontroller bewertet, ob ein Eingabeereignis mit einem der verwalteten Geräte. Ereignisse von verwalteten Geräten werden verarbeitet und genutzt.

Die Game Controller-Bibliothek unterstützt zwei Arten von Eingabeereignissen: AInputEvents und GameActivity Eingabeereignisse.

AInputEvent-Verarbeitung

Dein Spiel sollte AInputEvents weiterleiten, indem du anrufst: Paddleboat_processInputEvent aus dem Ereignisverarbeitungscode entfernt.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

Paddleboat_processInputEvent gibt 0 zurück, wenn das Ereignis ignoriert wurde, und 1 Ob das Ereignis verarbeitet und von der Game Controller-Bibliothek verarbeitet wurde.

Verarbeitung von GameActivity-Ereignissen

Wenn in deinem Spiel GameActivity verwendet wird, musst du GameActivityKeyEvent und GameActivityMotionEvent-Ereignisse durch den Aufruf von Paddleboat_processGameActivityKeyInputEvent oder Paddleboat_processGameActivityMotionInputEvent. aus dem Ereignisverarbeitungscode entfernt.

int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
                                                    const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
                                                       const size_t eventSize)

Parameter	Beschreibung
event	Ein Zeiger auf ein GameActivityKeyEvent- oder GameActivityMotionEvent-Struktur, je nach welche Funktion aufgerufen wird.
eventSize	Die Größe des Ereignisses in Byte Struktur, die mit dem Parameter event übergeben wird.

Beide Funktionen geben 0 zurück, wenn das Ereignis ignoriert wurde, und 1, wenn das Ereignis verarbeitet und von der Game Controller-Bibliothek genutzt werden.

Für GameActivity muss die aktive Bewegungsachse mithilfe des Parameters GameActivityPointerAxes_enableAxis verwenden. Die Paddleboat_getActiveAxisMask gibt eine Bitmaske der aktuell aktiven Bewegungsachse zurück, die von verbundenen Controller.

uint64_t Paddleboat_getActiveAxisMask()

Ein Beispiel zur Vorgehensweise finden Sie im Beispiel der Game Controller-Bibliothek. die GameActivity verwendet. Das Beispiel fragt die Maske der aktiven Achse ab GameActivity, wenn eine neue Achse verwendet wird. Dies wird in der 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;
        }
    }
}

Controller lesen

Die Game Controller-Bibliothek verwendet einen Indexwert, um auf eine bestimmte Verantwortliche. Gültige Indexwerte liegen zwischen 0 und PADDLEBOAT_MAX_CONTROLLERS - 1. Die Paddleboat_getControllerStatus -Funktion den Status eines angegebenen Controller-Index bestimmt.

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

Es gibt drei Funktionen zum Lesen von Informationen von einem verbundenen Controller.

• Die Paddleboat_getControllerName ruft den Namen des Controller-Geräts ab.
• Die Paddleboat_getControllerInfo ruft Daten zum Controller-Gerät selbst ab.
• Die Paddleboat_getControllerData ruft den aktuellen Status der Controllereingaben ab.

Controller name

Das Paddleboat_getControllerName function benötigt zwei Eingabeparameter: einen Controller-Index, eine Puffergröße und einen Zeiger auf einen Zwischenspeicher zum Speichern des Strings für den Controllernamen. Der String für den Namen ist formatiert als C-String mit UTF-8-Codierung. Der Name des Geräts wird intern abgerufen mit InputDevice.getName().

Wenn Paddleboat_getControllerName den Namen erfolgreich abruft, wird Folgendes zurückgegeben: PADDLEBOAT_NO_ERROR verwenden, andernfalls wird ein entsprechender Fehlercode zurückgegeben.

Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
                                                  const size_t bufferSize,
                                                  char *controllerName);

Parameter	Beschreibung
controllerIndex	Index des Controllers, der den Callback des Nutzers an. Ist ein Wert zwischen 0 und PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize	Größe des Zwischenspeichers in Byte, der übergeben wird controllerName ist der Namensstring. wenn nötig, um in den Puffer zu passen.
controllerName	Ein Zeiger auf einen Zwischenspeicher von bufferSize Byte in dem der Name des Controllers gespeichert werden soll. Der Name wird als C-String mit UTF-8-Codierung gespeichert werden.

Geräteinformationen zum Controller

Paddleboat_getControllerInfo function verwendet zwei Eingabeparameter: a Controller-Index und einen Zeiger auf eine Paddleboat_Controller_Info-Struktur.

Wenn Paddleboat_Controller_Info erfolgreich mit Daten gefüllt wurde, Paddleboat_getControllerInfo gibt PADDLEBOAT_NO_ERROR zurück, andernfalls ein wird der entsprechende Fehlercode zurückgegeben.

Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

Die Struktur „Paddleboat_Controller_Info“ enthält gerätespezifische Informationen über den Controller.

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;

Mehrere Strukturmitglieder werden mit Werten gefüllt, die aus dem InputDevice verknüpft mit Controller:

controllerNumber    -   InputDevice.getControllerNumber()
vendorId              - InputDevice.getVendorId()
productId             - InputDevice.getProductId()
deviceId              - InputDevice.getId()

• Ein stickFlat-Wert gibt die Größe einer flachen Mitte an. Dieser Wert ist hauptsächlich für die Berechnung einer Toleranzzone des Standardmittelpunkts nützlich. am selbstzentrierenden Geräten.
• Ein stickFuzz-Wert steht für die Fehlertoleranz, d. h. wie weit die aktuelle Der Wert kann aufgrund von Rauschen und der Geräteempfindlichkeit vom tatsächlichen Wert abweichen. Einschränkungen.

Beide Werte werden auf einen Achsenhöchstwert von 1.0 in beiden Dimensionen normalisiert.

Das Mitglied controllerFlags enthält eine Kombination aus einzelnen Bitmasken Flags und Multi-Bit-Kombinationswerte.

Ausführen eines logischen AND von controllerFlags mit PADDLEBOAT_CONTROLLER_LAYOUT_MASK führt zu einem Wert, der in den Paddleboat_ControllerButtonLayout-Enum. Diese Aufzählung gibt die Schaltfläche an, die vom Controller verwendeten Symbole und das Layout.

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
};

Die folgenden Konstanten definieren Funktionsbits. Um zu ermitteln, ob ein Controller eine bestimmte Capability unterstützt, führen Sie ein logisches AND der entsprechenden Konstante gegen controllerFlags. Ein Ergebnis ungleich null bedeutet, dass die Capability die vom Controller unterstützt werden.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

Wenn dieses Flag-Bit gesetzt ist, verfügt der Controller über ein integriertes Touchpad. Wenn die gedrückt wird, setzt der Controller das PADDLEBOAT_BUTTON_TOUCHPAD-Bit ein. Das Feld Paddleboat_Controller_Data.buttonsDown.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

Wenn dieses Flag-Bit gesetzt ist, emuliert der Controller ein Zeigergerät. Die virtualPointer Mitglied der Struktur „Paddleboat_Controller_Data“ ist mit den aktuellen Koordinaten des virtuellen Zeigers ausgefüllt.

Daten eines Verantwortlichen

Die Funktion Paddleboat_getControllerData verwendet zwei Eingabeparameter: a Controller-Index und einen Zeiger auf eine Paddleboat_Controller_Data-Struktur. Wenn Paddleboat_Controller_Data wurde mit Daten gefüllt, Paddleboat_getControllerInfo gibt PADDLEBOAT_NO_ERROR zurück, andernfalls ein wird der entsprechende Fehlercode zurückgegeben.

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

Die Struktur Paddleboat_Controller_Data enthält die aktuelle Steuerungseingabe Werte des Controllers.

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;

Wertebereiche

Eingabetyp	Wertebereich
Stickachse	-1.0 bis 1.0
Trigger	0.0 bis 1.0
Virtuelle Cursor	0.0 zu Fensterbreite/-höhe (in Pixeln)

Hinweis :Die meisten, aber nicht alle Controller unterstützen analoge Bereiche der L2/R2-Taste. Einige Controller haben digitale L2/R2-Tasten und melden entweder 0.0 oder 1.0. Die L1/R1-Trigger sind im Allgemeinen digital und melden entweder 0.0 oder 1.0, obwohl analoge Bereiche werden gemeldet, wenn sie vom Controller unterstützt werden. Trigger Legen Sie Bitmasken für die Schaltfläche fest, wenn sie gedrückt wird (mit anderen Worten, PADDLEBOAT_BUTTON_L1).

Gebäudedetails

Gebäudemitglied	Beschreibung
buttonsDown	Bit-pro-Button-Bitfeld-Array. Bitmaske für Schaltfläche sind in paddleboat.h definiert. Headerdatei und beginnen Sie mit PADDLEBOAT_BUTTON_
timestamp.	Zeitstempel der letzten Controllereingabe . Der Zeitstempel ist Mikrosekunden, da Epoche.
virtualPointer	Position des virtuellen Zeigers. Nur gültig, wenn das PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE-Flag ist in controllerFlags festgelegt. Andernfalls wird 0.0, 0.0