Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare la raccolta del controller di gioco

Utilizza le seguenti funzioni per aggiungere il supporto del controller di gioco al tuo gioco utilizzando la relativa raccolta.

Inizializzare e distruggere la libreria del controller di gioco

Utilizza la funzione Paddleboat_init per inizializzare la raccolta del controller di gioco.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init richiede due parametri:

Un puntatore a una JNIEnv collegato al thread corrente
Un riferimento a un oggetto JNI jobject a una classe derivata Context. Qualsiasi oggetto di classe derivato da Context è valido, inclusi, a titolo esemplificativo, Activity, NativeActivity o GameActivity.

Paddleboat_init restituisce PADDLEBOAT_NO_ERROR se l'inizializzazione è riuscita; in caso contrario, viene restituito un codice di errore appropriato.

Puoi utilizzare Paddleboat_isInitialized per verificare se la raccolta del controller di gioco è stata inizializzata correttamente. Restituisce un valore booleano. Se true, l'API è disponibile per l'uso.

bool Paddleboat_isInitialized()

Prima di terminare l'applicazione, utilizza la funzione Paddleboat_destroy per arrestare la raccolta del controller di gioco. La funzione accetta un singolo parametro, un puntatore a un JNIEnv collegato al thread corrente. Paddleboat_init potrebbe essere richiamato dopo il giorno Paddleboat_destroy.

void Paddleboat_destroy(JNIEnv *env)

Informa la libreria degli eventi del ciclo di vita

La libreria del controller di gioco deve essere informata degli eventi del ciclo di vita dell'attività onStop e onStart. Chiama le funzioni Paddleboat_onStop e Paddleboat_onStart dal codice di gestione degli eventi di stop e start. Entrambe le funzioni accettano un singolo parametro: un puntatore a un JNIEnv collegato al thread corrente.

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

Registra o rimuovi un callback dello stato del controller

La raccolta del controller di gioco utilizza un callback dello stato del controller per notificare un gioco quando un controller è collegato o disconnesso. Supporta un solo callback di stato del controller alla volta.

Per registrare un callback di stato del controller o sostituire qualsiasi callback registrato in precedenza con una nuova funzione di callback, chiama la funzione Paddleboat_setControllerStatusCallback.
Per rimuovere le richiamate attualmente registrate, supera NULL o nullptr.
Il parametro userData è un puntatore facoltativo ai dati definiti dall'utente. Il parametro userData verrà passato alla funzione di callback. Questo puntatore viene conservato internamente fino a quando non viene modificato da una chiamata successiva a 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 il callback. Sarà un valore compreso tra `0` e `PADDLEBOAT_MAX_CONTROLLERS - 1`
`controllerStatus`	Valore numerico di `PADDLEBOAT_CONTROLLER_JUST_CONNECTED` o `PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED`.
`userData`	Un puntatore facoltativo (potrebbe essere NULL) ai dati definiti dall'utente specificati dall'ultima chiamata a `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 vicino all'inizio del frame. La funzione accetta un singolo parametro, un puntatore a un JNIEnv collegato al thread corrente.

void Paddleboat_update(JNIEnv *env)

Elabora eventi

Quando ricevi eventi di input, il gioco deve inoltrarli alla raccolta del controller di gioco per l'ispezione. La libreria del controller di gioco valuta se un evento di input è associato a uno dei suoi dispositivi gestiti. Gli eventi provenienti dai dispositivi gestiti vengono elaborati e utilizzati.

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

Elaborazione di AInputEvent in corso...

Il gioco dovrebbe inoltrare AInputEvents chiamando Paddleboat_processInputEvent dal codice di gestione degli eventi.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

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

Elaborazione dell'evento GameActivity

Se il tuo gioco utilizza GameActivity, inoltra gli eventi GameActivityKeyEvent e GameActivityMotionEvent chiamando Paddleboat_processGameActivityKeyInputEvent o Paddleboat_processGameActivityMotionInputEvent dal codice di 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 una struttura `GameActivityKeyEvent` o `GameActivityMotionEvent`, a seconda della funzione chiamata.
`eventSize`	La dimensione in byte della struttura degli eventi passata nel parametro `event`.

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

GameActivity richiede che l'asse di movimento attivo venga specificato utilizzando la funzione GameActivityPointerAxes_enableAxis. La chiamata Paddleboat_getActiveAxisMask restituisce una maschera di bit dell'asse di movimento attualmente attivo utilizzata dai controller collegati.

uint64_t Paddleboat_getActiveAxisMask()

Per un esempio di come gestire questa operazione, vedi l'esempio della libreria del controller di gioco che utilizza GameActivity. Il campione esegue il polling della maschera dell'asse attivo e informa GameActivity quando viene utilizzato un nuovo asse. Questa operazione viene implementata nella 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;
        }
    }
}

Lettura dei controller

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

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

Esistono tre funzioni per leggere le informazioni da un controller collegato.

La funzione Paddleboat_getControllerName recupera il nome del dispositivo controller.
La funzione Paddleboat_getControllerInfo recupera dati sul dispositivo controller stesso.
La funzione Paddleboat_getControllerData recupera lo stato attuale degli ingressi del controller.

Nome controller

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

Se Paddleboat_getControllerName recupera il nome correttamente, 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 il callback. Sarà un valore compreso tra `0` e `PADDLEBOAT_MAX_CONTROLLERS - 1`
`bufferSize`	Dimensioni in byte del buffer passato da `controllerName`; la stringa nome verrà troncata, se necessario per rientrare nel buffer.
`controllerName`	Un puntatore a un buffer di `bufferSize` byte in cui archiviare il nome del controller. Il nome verrà memorizzato come stringa C utilizzando la codifica UTF-8.

Informazioni sul dispositivo titolare

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

Se i dati sono stati completati correttamente in Paddleboat_Controller_Info, Paddleboat_getControllerInfo restituisce PADDLEBOAT_NO_ERROR, altrimenti verrà restituito un 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 relative al 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 ricavati dall'elemento InputDevice associato al controller:

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

Un valore stickFlat rappresenta l'estensione di una posizione centrale. Questo valore è utile principalmente per calcolare una "zona morta" centrale predefinita sui dispositivi autocentrati.
Un valore stickFuzz rappresenta la tolleranza di errore o la misura in cui il valore attuale può discostarsi dal valore effettivo a causa di limitazioni di rumore e sensibilità del dispositivo.

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

Il membro controllerFlags contiene una combinazione di singoli flag con mascheramento di bit e valori di combinazione a più bit.

L'esecuzione di un AND logico di controllerFlags con PADDLEBOAT_CONTROLLER_LAYOUT_MASK restituisce un valore che può essere trasmesso all'enumerazione Paddleboat_ControllerButtonLayout. Questa enum specifica l'iconografia e il layout del pulsante 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 funzionalità. Per determinare se un controller supporta una determinata funzionalità, esegui un valore AND logico della costante corrispondente rispetto a controllerFlags. Un risultato diverso da zero significa che la funzionalità è supportata dal controller.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

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

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

Se questo bit flag è impostato, il controller emula un dispositivo puntatore. Il membro virtualPointer della struttura Paddleboat_Controller_Data è completato con le coordinate attuali del puntatore virtuale.

Dati del titolare

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

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

La struttura Paddleboat_Controller_Data contiene gli attuali valori di input di controllo 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 di input	Intervallo di valori
Asse della levetta	Da `-1.0` a `1.0`
Trigger	Da `0.0` a `1.0`
Puntatori virtuali	`0.0` alla larghezza/all'altezza della finestra (in pixel)

Dettagli della struttura

Membro della struttura	Descrizione
`buttonsDown`	Array di bit-per-button. Le costanti della maschera di bit dei pulsanti sono definite nel file di intestazione paddleine.h. e iniziano con `PADDLEBOAT_BUTTON_`.
`timestamp.`	Timestamp dell'evento di input del controller più recente. Il timestamp è di microsecondi dall'epoca dell'orologio.
`virtualPointer`	Posizione del puntatore virtuale. Valido solo se il flag `PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE` è impostato in `controllerFlags`, altrimenti sarà `0.0, 0.0`.