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 raccolta del controller di gioco.

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 associato al thread corrente
Un riferimento di oggetto JNI jobject a una classe derivata Context. Qualsiasi oggetto di classe derivato Context è valido, inclusi, a titolo esemplificativo, Activity, NativeActivity o GameActivity.

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

Puoi utilizzare Paddleboat_isInitialized per verificare se la libreria del controller di gioco è stata inizializzata correttamente. Restituisce un valore booleano. Se il valore è 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 utilizza 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 raccolta del controller di gioco deve essere informata del ciclo di vita dell'attività onStop e degli eventi onStart. Richiama le funzioni Paddleboat_onStop and Paddleboat_onStart dal codice di gestione degli eventi di interruzione e avvio. 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 inviare una notifica a un gioco quando un controller è collegato o disconnesso. Supporta un solo callback di stato del controller alla volta.

Per registrare un callback dello stato del controller o sostituire un callback registrato in precedenza con una nuova funzione di callback, chiama la funzione Paddleboat_setControllerStatusCallback.
Per rimuovere qualsiasi callback attualmente registrato, passa 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 enum 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`.

Chiamata alla funzione di aggiornamento della raccolta 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 utilizza un singolo parametro, un puntatore a un JNIEnv collegato al thread corrente.

void Paddleboat_update(JNIEnv *env)

Elabora gli 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 consumati.

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

Elaborazione AInputEvent

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 degli eventi 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`	Le dimensioni in byte della struttura dell'evento 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 sia specificato utilizzando la funzione GameActivityPointerAxes_enableAxis. La chiamata Paddleboat_getActiveAxisMask restituisce una maschera di bit dell'asse di movimento attualmente attivo utilizzata dai controller connessi.

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 controller

La libreria dei 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 relativi al dispositivo controller stesso.
La funzione Paddleboat_getControllerData recupera lo stato attuale degli ingressi del controller.

Nome titolare

Paddleboat_getControllerName function richiede due parametri di input: un indice del controller, una dimensione del buffer e un puntatore a un buffer per memorizzare la stringa del nome del controller. La stringa del nome viene formattata come stringa C con 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 del 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 richiede due parametri di input: un indice controller e un puntatore a una struttura Paddleboat_Controller_Info.

Se Paddleboat_Controller_Info è stato compilato correttamente con i dati, Paddleboat_getControllerInfo restituisce PADDLEBOAT_NO_ERROR, altrimenti viene 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 sul controller specifiche per il dispositivo.

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 acquisiti dal 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 piatta al centro. 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 delle limitazioni di rumore e sensibilità del dispositivo.

Entrambi i valori sono normalizzati su un valore massimo dell'asse 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 genera un valore che può essere trasmesso all'enum Paddleboat_ControllerButtonLayout. Questa enum specifica l'icona 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 indica che la funzionalità è supportata dal controller.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

Se questa bit di segnalazione è impostata, 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 di flag è impostato, il controller emula un dispositivo puntatore. Il membro virtualPointer della struttura Paddleboat_Controller_Data viene compilato con le coordinate correnti del puntatore virtuale.

Dati del titolare

La funzione Paddleboat_getControllerData accetta due parametri di input: un indice del 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 ingresso 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 input	Intervallo di valori
Asse del pollice	Da `-1.0` a `1.0`
Trigger	Da `0.0` a `1.0`
Puntatori virtuali	`0.0` rispetto alla larghezza/altezza della finestra (in pixel)

Dettagli struttura

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