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 derivataContext
. Qualsiasi oggetto di classe derivato daContext
è valido, inclusi, a titolo esemplificativo,Activity
,NativeActivity
oGameActivity
.
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
onullptr
. - Il parametro
userData
è un puntatore facoltativo ai dati definiti dall'utente. Il parametrouserData
verrà passato alla funzione di callback. Questo puntatore viene conservato internamente fino a quando non viene modificato da una chiamata successiva aPaddleboat_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 . |