Korzystanie z biblioteki kontrolerów gier

Poniższe funkcje pozwolą dodać obsługę kontrolera do gier za pomocą w bibliotece kontrolera gier.

Inicjowanie i zniszczenie biblioteki kontrolera gier

Korzystanie z Paddleboat_init zainicjuj bibliotekę kontrolera gier.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Funkcja Paddleboat_init przyjmuje 2 parametry:

• wskaźnik do JNIEnv. dołączony do bieżącego wątku
• Odwołanie do obiektu JNI jobject do klasa derywowana Context. Dowolny Context obiekt klasy derywowanej jest prawidłowy, w tym między innymi Activity, NativeActivity, lub GameActivity.

Paddleboat_init za możliwość zwrotu PADDLEBOAT_NO_ERROR, jeśli inicjowanie się udało. W przeciwnym razie użyj odpowiedniego kodu błędu. .

Za pomocą Paddleboat_isInitialized możesz sprawdzić, czy Gra Biblioteka kontrolera została zainicjowana. Zwraca wartość logiczną . Jeśli ma wartość prawda, interfejs API jest dostępny.

bool Paddleboat_isInitialized()

Przed zamknięciem aplikacji użyj przycisku Paddleboat_destroy wyłącza ją. Funkcja przyjmuje pojedynczą i wskaźnikiem do elementu JNIEnv dołączonego do bieżącego wątku. Użytkownik Paddleboat_init może zostać wywołany ponownie po Paddleboat_destroy.

void Paddleboat_destroy(JNIEnv *env)

Informacje o bibliotece zdarzeń cyklu życia

W bibliotece Kontrolera gier należy zapoznać się z cykl życia aktywności onStop i Zdarzenia: onStart. Wywołaj funkcję Paddleboat_onStop oraz Paddleboat_onStart za pomocą funkcji zatrzymania i uruchamiania kodu obsługi zdarzeń. Obie funkcje przyjmują pojedynczy parametr: wskaźnik do elementu JNIEnv dołączonego do bieżącego wątku.

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

Rejestrowanie lub usuwanie wywołania zwrotnego stanu kontrolera

Biblioteka kontrolera gier powiadamia grę za pomocą wywołania zwrotnego stanu kontrolera gdy kontroler jest podłączony lub odłączony. Obsługuje tylko 1 kontroler stanu.

• Aby zarejestrować wywołanie zwrotne stanu kontrolera lub zastąpić dowolne wcześniejsze zarejestrowane wywołanie zwrotne z nową funkcją wywołania zwrotnego, wywołaj metodę Paddleboat_setControllerStatusCallback.
• Aby usunąć aktualnie zarejestrowane wywołanie zwrotne, przekaż NULL lub nullptr.
• Parametr userData jest opcjonalnym wskaźnikiem do danych zdefiniowanych przez użytkownika. Parametr userData zostanie przekazany do funkcji wywołania zwrotnego. Ten wskaźnik jest zachowywany wewnętrznie do czasu zmiany przez kolejne wywołanie funkcji Paddleboat_setControllerStatusCallback

void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

Podpis funkcji wywołania zwrotnego to:

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

Parametr	Opis
controllerIndex	Indeks kontrolera, który zainicjował oddzwanianie. Będzie zawierać wartość z zakresu od 0 do PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus	Wartość enum PADDLEBOAT_CONTROLLER_JUST_CONNECTED lub PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED
userData	Opcjonalny wskaźnik (może mieć wartość NULL) do użytkownika zdefiniowane dane określone przez ostatnie wywołanie Paddleboat_setControllerStatusCallback

Wywołaj funkcję aktualizacji biblioteki kontrolera gier

Funkcja aktualizacji biblioteki kontrolera gier. Paddleboat_update , powinna być wywoływana raz na klatkę gry, najlepiej na początku klatki. Funkcja przyjmuje 1 parametr, czyli wskaźnik do elementu JNIEnv dołączonego do w bieżącym wątku.

void Paddleboat_update(JNIEnv *env)

Przetwarzaj zdarzenia

Podczas odbierania zdarzeń wejściowych, gra musi: i przekazać je do biblioteki kontrolera gier w celu sprawdzenia. Kontroler do gier ocenia, czy zdarzenie wejściowe jest powiązane z jednym z zarządzanych przez niego zdarzeń urządzenia. Zdarzenia z urządzeń zarządzanych są przetwarzane i wykorzystywane.

Biblioteka kontrolera gier obsługuje 2 typy zdarzeń wejściowych: AInputEvents i Zdarzenia wejściowe GameActivity.

Przetwarzanie AInputEvent

Twoja gra powinna przekazać AInputEvents, dzwoniąc pod numer Paddleboat_processInputEvent. za pomocą kodu obsługi zdarzeń.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

Paddleboat_processInputEvent zwraca wartość 0, jeśli zdarzenie zostało zignorowane, oraz 1. wskazuje, czy zdarzenie zostało przetworzone i wykorzystane przez bibliotekę kontrolera gier.

Przetwarzanie zdarzeń GameActivity

Jeśli gra używa GameActivity, prześlij dalej GameActivityKeyEvent i wydarzeń związanych z GameActivityMotionEvent przez połączenie telefoniczne. Paddleboat_processGameActivityKeyInputEvent lub Paddleboat_processGameActivityMotionInputEvent za pomocą kodu obsługi zdarzeń.

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

Parametr	Opis
event	wskaźnik do: GameActivityKeyEvent lub GameActivityMotionEvent struktura w zależności od która jest wywoływana.
eventSize	Rozmiar zdarzenia w bajtach strukturę przekazywaną w parametrze event.

Obie funkcje będą zwracać wartość 0, jeśli zdarzenie zostało zignorowane, oraz 1, jeśli zdarzenie zostało które są przetwarzane i wykorzystywane przez bibliotekę kontrolera gier.

Funkcja GameActivity wymaga określenia aktywnej osi ruchu za pomocą funkcji GameActivityPointerAxes_enableAxis. Paddleboat_getActiveAxisMask zwraca maskę bitową obecnie aktywnej osi ruchu używanej przez połączone i kontrolerach.

uint64_t Paddleboat_getActiveAxisMask()

Przykład znajdziesz w przykładowej bibliotece kontrolera gier. który korzysta z GameActivity. Przykład sonduje aktywną maskę osi i informuje GameActivity, gdy używana jest nowa oś. Jest to implementowane w 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;
        }
    }
}

Odczyt kontrolerów

Biblioteka kontrolera gier wykorzystuje wartość indeksu w odniesieniu do konkretnego kontrolerem. Prawidłowe wartości indeksu od 0 do PADDLEBOAT_MAX_CONTROLLERS - 1 Paddleboat_getControllerStatus określa stan określonego indeksu kontrolera.

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

Z podłączonego kontrolera dostępne są 3 funkcje odczytu informacji.

• Paddleboat_getControllerName pobiera nazwę urządzenia kontrolera.
• Paddleboat_getControllerInfo pobiera dane o samym urządzeniu kontrolera.
• Paddleboat_getControllerData pobiera bieżący stan danych wejściowych kontrolera.

Nazwa kontrolera

Paddleboat_getControllerName function przyjmuje 2 parametry wejściowe: indeks kontrolera, rozmiar bufora i wskaźnik do bufor do przechowywania ciągu nazwy kontrolera. Ciąg nazwy ma format Ciąg znaków C z kodowaniem UTF-8. Nazwa urządzenia jest uzyskiwana wewnętrznie za pomocą funkcji InputDevice.getName().

Jeśli Paddleboat_getControllerName pobierze nazwę, zwróci nazwę PADDLEBOAT_NO_ERROR, w przeciwnym razie zostanie zwrócony odpowiedni kod błędu.

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

Parametr	Opis
controllerIndex	Indeks kontrolera, który zainicjował oddzwanianie. Będzie zawierać wartość z zakresu od 0 do PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize	Rozmiar w bajtach przekazywanego bufora controllerName, nazwą będzie ciąg znaków. w razie potrzeby skrócony, aby zmieścić się w buforze.
controllerName	Wskaźnik do bufora o długości bufferSize bajtów w którym chcesz zapisać nazwę kontrolera. Nazwa będzie mogą być przechowywane jako ciąg C z kodowaniem UTF-8.

Informacje o kontrolerze

Funkcja Paddleboat_getControllerInfo function przyjmuje 2 parametry wejściowe: w indeksie kontrolera i wskaźniku do struktury Paddleboat_Controller_Info.

Jeśli pole Paddleboat_Controller_Info zostało wypełnione danymi, Paddleboat_getControllerInfo zwraca wartość PADDLEBOAT_NO_ERROR, w przeciwnym razie zwraca zwracany jest odpowiedni kod błędu.

Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

Struktura Paddleboat_Controller_Info zawiera informacje o poszczególnych urządzeniach na temat administratora.

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;

Kilka elementów struct jest wypełnianych wartościami pobranymi z InputDevice powiązane z kontroler:

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

• Wartość stickFlat określa zakres środkowej, płaskiej pozycji. Ta wartość jest przydatna przy obliczaniu domyślnej środkowej „strefy martwej” włączono urządzeń samośrodkowych.
• Wartość stickFuzz reprezentuje tolerancję błędów, czyli odległość, w jakiej bieżąca wartość może odbiegać od wartości rzeczywistej ze względu na szum i czułość urządzenia i ograniczeniach.

Obie wartości są normalizowane do maksymalnej wartości na osi 1.0 w każdym wymiarze.

Element controllerFlags zawiera kombinację poszczególnych masek bitowych flagi i wielobitowych kombinacji wartości.

Wykonuję logiczną AND z controllerFlags – PADDLEBOAT_CONTROLLER_LAYOUT_MASK daje wartość, która może być rzutowana na funkcję Wyliczenie Paddleboat_ControllerButtonLayout. Ta enum określa przycisk ikony i układ kontrolera.

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

Te stałe określają bity możliwości. Aby określić, czy kontroler obsługuje konkretną funkcję, wykonaj logiczne AND dla odpowiednich stałą w porównaniu z controllerFlags. Wynik inny niż zero oznacza, że umiejętność jest obsługiwane przez kontroler.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

Jeśli ten bit flagi jest ustawiony, kontroler ma zintegrowany touchpad. Jeśli touchpad jest naciśnięty, kontroler ustawia bit PADDLEBOAT_BUTTON_TOUCHPAD w polu Paddleboat_Controller_Data.buttonsDown.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

Jeśli ten bit flagi jest ustawiony, kontroler emuluje urządzenie wskazujące. virtualPointer element struktury Paddleboat_Controller_Data to zawiera aktualne współrzędne wirtualnego wskaźnika.

Dane przetwarzane przez administratora

Funkcja Paddleboat_getControllerData przyjmuje 2 parametry wejściowe: w indeksie kontrolera i wskaźniku do struktury Paddleboat_Controller_Data. Jeśli Pole Paddleboat_Controller_Data zostało wypełnione danymi, Paddleboat_getControllerInfo zwraca wartość PADDLEBOAT_NO_ERROR, w przeciwnym razie zwraca zwracany jest odpowiedni kod błędu.

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

Struktura Paddleboat_Controller_Data zawiera bieżące dane wejściowe na kontrolerze.

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;

Zakresy wartości

Typ danych wejściowych	Zakres wartości
Osie kciuka	Od -1.0 do 1.0
Aktywatory	Od 0.0 do 1.0
Wirtualne wskaźniki	0.0 do szerokości/wysokości okna (w pikselach)

Uwaga: większość kontrolerów, ale nie wszystkie, obsługuje zakresy analogowe z przyciskami L2/R2. Niektóre kontrolery mają cyfrowe przyciski L2/R2 i zgłaszają 0.0 lub 1.0. Reguły L1/R1 są zwykle cyfrowe i zgłaszają 0.0 lub 1.0, chociaż zakresy analogowe są zgłaszane, jeśli kontroler je obsługuje. Reguły będą też ustawia maski bitowe przycisków po naciśnięciu (czyli PADDLEBOAT_BUTTON_L1).

Szczegóły struktury

Członek struktury	Opis
buttonsDown	Tablica bitowa pola bitowego z podziałem na przycisk. Maska bitowa przycisku stałe zdefiniowane w adresie paddleboat.h. pliku nagłówka i zaczynają się od PADDLEBOAT_BUTTON_
timestamp.	Sygnatura czasowa ostatniego działania kontrolera . Sygnatura czasowa jest wyrażona w mikrosekundach, ponieważ epoki zegara.
virtualPointer	Lokalizacja wirtualnego wskaźnika. Prawidłowa tylko wtedy, gdy Flaga PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE jest ustawiona na controllerFlags, w przeciwnym razie jest 0.0, 0.0