Utilizzare la raccolta del controller di gioco

Usa le seguenti funzioni per aggiungere il supporto del controller di gioco al tuo gioco usando nella libreria del controller di gioco.

Inizializza ed elimina la libreria del controller di gioco

Utilizza la Paddleboat_init per inizializzare la libreria del controller di gioco.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init richiede due parametri:

  • Un puntatore a una JNIEnv allegato al thread corrente
  • Un riferimento di oggetto JNI jobject a un Classe derivata Context. Qualsiasi Context di classe derivata è valida, inclusa, a titolo esemplificativo, Activity, NativeActivity, o GameActivity.

Resi a Paddleboat_init PADDLEBOAT_NO_ERROR se l'inizializzazione è riuscita, altrimenti viene visualizzato un codice di errore appropriato. viene restituito.

Puoi utilizzare Paddleboat_isInitialized per verificare se il Gioco La libreria controller è stata inizializzata. Restituisce un valore booleano valore. Se impostato su true, l'API è disponibile per l'uso.

bool Paddleboat_isInitialized()

Prima di terminare l'applicazione, utilizza il Paddleboat_destroy per chiudere la libreria del controller di gioco. La funzione prende una singola , un puntatore a un JNIEnv allegato al thread corrente. Paddleboat_init potrà essere richiamato dopo le ore Paddleboat_destroy.

void Paddleboat_destroy(JNIEnv *env)

Informa la libreria degli eventi del ciclo di vita

La raccolta del controller di gioco deve essere informata ciclo di vita dell'attività onStop e onStart eventi. Chiama il Paddleboat_onStop e Paddleboat_onStart dal codice di gestione degli eventi di interruzione e avvio. Entrambe le funzioni prendono un singolo parametro: un puntatore a un JNIEnv allegato al thread corrente.

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

Registra o rimuovi un callback dello stato del controller

La raccolta dei controller di gioco utilizza un callback dello stato del controller per inviare una notifica a un gioco quando un controller è connesso o disconnesso. Supporta un solo controller alla volta.

  • Per registrare un callback dello stato del controller o sostituire quelli precedenti con una nuova funzione di callback, richiama il Paddleboat_setControllerStatusCallback.
  • Per rimuovere qualsiasi callback attualmente registrato, passa NULL o nullptr.
  • Il parametro userData è un puntatore facoltativo ai dati definiti dall'utente. La Il parametro userData verrà passato alla funzione di callback. Questo puntatore vengono conservati internamente finché non vengono modificati da una chiamata successiva Paddleboat_setControllerStatusCallback.
void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

La firma della funzione di callback è:

typedef void (*Paddleboat_ControllerStatusCallback)(
  const int32_t controllerIndex,
  const Paddleboat_ControllerStatus controllerStatus,
  void *userData)
Parametro Descrizione
controllerIndex Indice del controller che ha avviato la di Google. Sarà un valore compreso tra 0 e
PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus Valore enum di PADDLEBOAT_CONTROLLER_JUST_CONNECTED o
PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED.
userData Un puntatore facoltativo (potrebbe essere NULL) all'utente i dati definiti e specificati dall'ultima chiamata Paddleboat_setControllerStatusCallback.

Chiama la funzione di aggiornamento della libreria del controller di gioco

La funzione di aggiornamento della libreria del controller di gioco Paddleboat_update , deve essere chiamata una volta per frame di gioco, preferibilmente all'inizio del frame. La funzione utilizza un singolo parametro, un puntatore a un JNIEnv collegato alla thread attuale.

void Paddleboat_update(JNIEnv *env)

Eventi di elaborazione

Quando ricevi eventi di input, il gioco deve lo inoltra alla raccolta del controller di gioco per ispezionarli. Il controller di gioco libreria valuta se un evento di input è associato a una delle sue dispositivi mobili. Gli eventi dei dispositivi gestiti vengono elaborati e consumati.

La libreria del controller di gioco supporta due tipi di eventi di input: AInputEvents e GameActivity eventi di input.

Elaborazione AInputEvent

La tua partita dovrebbe inoltrare AInputEvents chiamando Paddleboat_processInputEvent dal codice per la gestione degli eventi.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

Paddleboat_processInputEvent restituirà 0 se l'evento è stato ignorato e 1 se l'evento è stato elaborato e utilizzato dalla raccolta del controller di gioco.

Elaborazione eventi GameActivity

Se il tuo gioco usa GameActivity, inoltra GameActivityKeyEvent e GameActivityMotionEvent tramite la chiamata Paddleboat_processGameActivityKeyInputEvent o Paddleboat_processGameActivityMotionInputEvent dal codice per la gestione degli eventi.

int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
                                                    const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
                                                       const size_t eventSize)
Parametro Descrizione
event Un puntatore a un GameActivityKeyEvent o della struttura GameActivityMotionEvent, a seconda su quale funzione viene chiamata.
eventSize Le dimensioni in byte dell'evento struttura passata nel parametro event.

Entrambe le funzioni restituiranno 0 se l'evento è stato ignorato e 1 se l'evento è stato elaborati e consumati dalla libreria del controller di gioco.

GameActivity richiede che l'asse di movimento attivo sia specificato utilizzando il metodo Funzione GameActivityPointerAxes_enableAxis. La Paddleboat_getActiveAxisMask restituisce una maschera di bit dell'asse di movimento attualmente attivo utilizzato controller.

uint64_t Paddleboat_getActiveAxisMask()

Per un esempio di come gestire questa situazione, guarda l'esempio della libreria del controller di gioco che utilizza GameActivity. L'esempio esegue il polling della maschera dell'asse attivo e fornisce informazioni GameActivity quando viene utilizzato il nuovo asse. Questa funzionalità viene implementata nel Funzione 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;
        }
    }
}

Leggi i controller

La libreria dei controller di gioco utilizza un valore di indice per fare riferimento a uno specifico un controller di deployment. I valori di indice validi sono compresi tra 0 e PADDLEBOAT_MAX_CONTROLLERS - 1. La Paddleboat_getControllerStatus determina lo stato di un indice del controller specificato.

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

Esistono tre funzioni per la lettura delle informazioni da un controller collegato.

Nome controller

Paddleboat_getControllerName function accetta due parametri di input: un indice del controller, una dimensione del buffer e un puntatore un buffer per memorizzare la stringa del nome del controller. La stringa del nome è formattata come stringa C con codifica UTF-8. Il nome del dispositivo viene ottenuto internamente utilizzando InputDevice.getName().

Se Paddleboat_getControllerName recupera correttamente il nome, restituisce PADDLEBOAT_NO_ERROR, altrimenti viene restituito un codice di errore appropriato.

Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
                                                  const size_t bufferSize,
                                                  char *controllerName);
Parametro Descrizione
controllerIndex Indice del controller che ha avviato la di Google. Sarà un valore compreso tra 0 e
PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize Dimensione in byte del buffer passato controllerName, la stringa del nome sarà. troncato se necessario per adattarlo al buffer.
controllerName Un puntatore a un buffer di bufferSize byte in cui memorizzare il nome del controller. Il nome come stringa C utilizzando la codifica UTF-8.

Informazioni sul dispositivo controller

Paddleboat_getControllerInfo function accetta due parametri di input: a dell'indice del controller e un puntatore a una struttura Paddleboat_Controller_Info.

Se Paddleboat_Controller_Info sono stati compilati correttamente con i dati, Paddleboat_getControllerInfo restituisce PADDLEBOAT_NO_ERROR, altrimenti viene generato venga restituito il codice di errore appropriato.

Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

La struttura Paddleboat_Controller_Info contiene informazioni specifiche del dispositivo sul 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;

Diversi membri dello struct sono compilati da valori presi dal InputDevice associato al un controller:

controllerNumber    -   InputDevice.getControllerNumber()
vendorId              - InputDevice.getVendorId()
productId             - InputDevice.getProductId()
deviceId              - InputDevice.getId()
  • Un valore stickFlat rappresenta l'estensione di una posizione piana al centro. Questo valore è utile principalmente per calcolare una "zona morta" predefinita centrale attivo i dispositivi autocentranti.
  • Un valore stickFuzz rappresenta la tolleranza di errore o di quanto tempo potrebbe discostarsi dal valore effettivo a causa del rumore e della sensibilità del dispositivo limitazioni.

Entrambi i valori sono normalizzati su un valore massimo dell'asse pari a 1.0 in entrambe le dimensioni.

Il membro controllerFlags contiene una combinazione di singoli bitmasked e valori di combinazione a più bit.

È in corso l'esecuzione di un AND logico di controllerFlags con PADDLEBOAT_CONTROLLER_LAYOUT_MASK genera un valore che potrebbe essere trasmesso alla Enum. Paddleboat_ControllerButtonLayout Questa enum specifica il pulsante l'iconografia e il layout utilizzati dal controller.

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

Le seguenti costanti definiscono i bit di capacità. Per determinare se un controller supporta una particolare funzionalità, eseguire un AND logico dei costante rispetto a controllerFlags. Un risultato diverso da zero indica che la funzionalità è supportate dal controller.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

Se il bit di flag è impostato, il controller ha un touchpad integrato. Se il touchpad viene premuto, il controller imposta il PADDLEBOAT_BUTTON_TOUCHPAD bit il campo Paddleboat_Controller_Data.buttonsDown.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

Se il bit di questo flag è impostato, il controller emula un dispositivo di puntamento. La virtualPointer membro della struttura Paddleboat_Controller_Data è con le coordinate correnti del puntatore virtuale.

Dati del titolare

La funzione Paddleboat_getControllerData accetta due parametri di input: a dell'indice del controller e un puntatore a una struttura Paddleboat_Controller_Data. Se Paddleboat_Controller_Data è stato compilato correttamente con i dati, Paddleboat_getControllerInfo restituisce PADDLEBOAT_NO_ERROR, altrimenti viene generato venga restituito il codice di errore appropriato.

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

La struttura Paddleboat_Controller_Data contiene l'input di controllo corrente i valori del controller.

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;

Intervalli di valori

Tipo input Intervallo di valori
Asse levetta Da -1.0 a 1.0
Trigger Da 0.0 a 1.0
Puntatori virtuali 0.0 alla larghezza/altezza della finestra (in pixel)

Dettagli struttura

Membro della struttura Descrizione
buttonsDown Array di bit per pulsante. Maschera di bit pulsante le costanti sono definite nel file paddle boat.h. file di intestazione e iniziare con PADDLEBOAT_BUTTON_.
timestamp. Timestamp dell'input del controller più recente . Il timestamp è espresso in microsecondi da quando dell'orologio.
virtualPointer Posizione del puntatore virtuale. Valido solo se PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE flag è impostato in controllerFlags, altrimenti sarà 0.0, 0.0.