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 derivataContext
. Qualsiasi oggetto di classe derivatoContext
è valido, inclusi, a titolo esemplificativo,Activity
,NativeActivity
oGameActivity
.
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
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 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 . |