Oyun Kumandası kitaplığını kullanarak oyununuza oyun kumandası desteği eklemek için aşağıdaki işlevleri kullanın.
Oyun Denetleyicisi kitaplığını başlatma ve kaldırma
Oyun Kumandası kitaplığını ilk kullanıma hazırlamak için Paddleboat_init
işlevini kullanın.
Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)
Paddleboat_init
iki parametre alır:
- Mevcut iş parçacığına ekli bir
JNIEnv
işaretçisi Context
türetilmiş bir sınıfajobject
JNI nesne referansı.Activity
,NativeActivity
veyaGameActivity
dahil ancak bunlarla sınırlı olmamak üzere,Context
ile türetilen tüm sınıf nesneleri geçerlidir.
Başlatma başarılı olduysa Paddleboat_init
, PADDLEBOAT_NO_ERROR
değerini döndürür; aksi takdirde uygun bir hata kodu döndürülür.
Game Controller kitaplığının başarıyla başlatılıp başlatılmadığını kontrol etmek için Paddleboat_isInitialized
aracını kullanabilirsiniz. Boole değeri döndürür. Değer true ise API kullanılabilir.
bool Paddleboat_isInitialized()
Uygulamayı sonlandırmadan önce Paddleboat_destroy
işlevini kullanarak Oyun Kumandası kitaplığını kapatın. İşlev tek bir parametre alır; mevcut iş parçacığına ekli bir JNIEnv
işaretçisi.
Paddleboat_init
, Paddleboat_destroy
tarihinden sonra tekrar çağrılabilir.
void Paddleboat_destroy(JNIEnv *env)
Yaşam döngüsü olayları kitaplığına bilgi sağlar
Oyun Kumandası kitaplığı, etkinlik yaşam döngüsü
onStop
ve onStart
etkinlikleri hakkında bilgilendirilmelidir.
Stop and start etkinlik işleme kodunuzdan Paddleboat_onStop
ve Paddleboat_onStart
işlevlerini çağırın. Her iki işlev de tek bir parametre alır: mevcut iş parçacığına ekli bir JNIEnv
işaretçisi.
void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)
Denetleyici durumu geri çağırması kaydetme veya kaldırma
Oyun Kumandası kitaplığı, bir kumanda bağlandığında veya bağlantısı kesildiğinde oyunu bildirmek için kumandanın durum geri çağırma özelliğini kullanır. Aynı anda yalnızca bir kumanda durumu geri çağırmasını destekler.
- Bir denetleyici durumu geri çağırması kaydetmek veya daha önce kaydedilmiş bir geri çağırma işlevini yeni bir geri çağırma işleviyle değiştirmek için
Paddleboat_setControllerStatusCallback
işlevini çağırın. - Kayıtlı durumdaki geri aramaları kaldırmak için
NULL
veyanullptr
numarasını iletin. userData
parametresi, kullanıcı tanımlı verilere yönelik isteğe bağlı bir işaretçidir.userData
parametresi, geri çağırma işlevine aktarılır. Bu işaretçi, sonraki birPaddleboat_setControllerStatusCallback
çağrısıyla değiştirilene kadar dahili olarak tutulur.
void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
statusCallback, void *userData)
Geri çağırma işlevinin işlev imzası şudur:
typedef void (*Paddleboat_ControllerStatusCallback)(
const int32_t controllerIndex,
const Paddleboat_ControllerStatus controllerStatus,
void *userData)
Parametre | Açıklama |
---|---|
controllerIndex
|
Geri çağırmayı başlatan denetleyicinin dizini. 0 ile arasında bir değer olacaktır PADDLEBOAT_MAX_CONTROLLERS - 1 |
controllerStatus
|
PADDLEBOAT_CONTROLLER_JUST_CONNECTED veya PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED sıralama değeri. |
userData
|
Son Paddleboat_setControllerStatusCallback çağrısında belirtilen kullanıcı tanımlı verilere isteğe bağlı bir işaretçi (NULL olabilir). |
Oyun Kumandası kitaplığını güncelleme işlevini çağırma
Oyun Kumandası kitaplığı güncelleme işlevi Paddleboat_update
, oyun karesi başına bir kez (tercihen karenin başına yakın yerde) çağrılmalıdır.
İşlev tek bir parametre alır. Bu, geçerli iş parçacığına ekli bir JNIEnv
işaretçisi olur.
void Paddleboat_update(JNIEnv *env)
Etkinlikleri işleme
Giriş etkinlikleri alındığında, oyununuzun bunları inceleme için Oyun Denetleyicisi kitaplığına yönlendirmesi gerekir. Oyun Denetleyicisi kitaplığı, bir giriş etkinliğinin yönetilen cihazlarından biriyle ilişkili olup olmadığını değerlendirir. Yönetilen cihazlardan gelen etkinlikler işlenir ve tüketilir.
Oyun Denetleyici kitaplığı iki tür giriş etkinliğini destekler: AInputEvents
ve GameActivity
giriş etkinlikleri.
AInputEvent işleme
Oyununuz, etkinlik işleme kodunuzdan Paddleboat_processInputEvent
yöntemini çağırarak AInputEvents
alanını yönlendirmelidir.
int32_t Paddleboat_processInputEvent(const AInputEvent *event)
Paddleboat_processInputEvent
, etkinlik yoksayıldıysa 0
değerini, Oyun Denetleyici kitaplığı tarafından işlenip tüketildiyse 1
sonucunu döndürür.
GameActivity etkinliği işleniyor
Oyununuz GameActivity
kullanıyorsa
GameActivityKeyEvent
ve
GameActivityMotionEvent
etkinliklerini
Paddleboat_processGameActivityKeyInputEvent
veya
Paddleboat_processGameActivityMotionInputEvent
etkinliği işleme kodunuzdan çağırarak yönlendirin.
int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
const size_t eventSize)
Parametre | Açıklama |
---|---|
event
|
Çağrılan işlevine bağlı olarak, GameActivityKeyEvent veya GameActivityMotionEvent yapısına işaret eden bir işarettir. |
eventSize
|
event parametresinde iletilen etkinlik yapısının bayt cinsinden boyutu. |
Etkinlik yoksayılırsa 0
ve Oyun Denetleyici kitaplığı tarafından işlenip tüketilmişse her iki işlev de 1
değerini döndürür.
GameActivity
için aktif hareket ekseninin GameActivityPointerAxes_enableAxis
işlevi kullanılarak belirtilmesi gerekir. Paddleboat_getActiveAxisMask
çağrısı, bağlı denetleyiciler tarafından kullanılan, geçerli olarak aktif hareket ekseninin bit maskesini döndürür.
uint64_t Paddleboat_getActiveAxisMask()
Bunun nasıl yapılacağını gösteren örnek için GameActivity
kullanan Oyun Kumandası kitaplığı örneğine bakın. Örnek, etkin eksen maskesini yoklar ve yeni eksen kullanıldığında GameActivity
hakkında bilgi verir. Bu, NativeEngine::CheckForNewAxis()
işlevinde uygulanır.
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;
}
}
}
Denetleyicileri oku
Oyun Denetleyici kitaplığı, belirli bir denetleyiciyi belirtmek için bir dizin değeri kullanır. Geçerli dizin değerleri 0
ile PADDLEBOAT_MAX_CONTROLLERS - 1
aralığındadır. Paddleboat_getControllerStatus
işlevi, belirtilen bir denetleyici dizininin durumunu belirler.
Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
const int32_t controllerIndex)
Bağlı bir kumandadan bilgi okumak için üç işlev kullanılabilir.
Paddleboat_getControllerName
işlevi, kumanda cihazının adını alır.Paddleboat_getControllerInfo
işlevi, kumanda cihazının kendisiyle ilgili verileri alır.Paddleboat_getControllerData
işlevi, denetleyici girişlerinin mevcut durumunu alır.
Kumanda adı
Paddleboat_getControllerName function
iki giriş parametresi alır: bir denetleyici dizini, bir arabellek boyutu ve denetleyici ad dizesini saklayacak bir arabelleğe işaret eden bir işaretçi. Ad dizesi, UTF-8 kodlaması kullanılarak C dizesi olarak biçimlendirilir. Cihazın adı, InputDevice.getName()
kullanılarak dahili olarak alınır.
Paddleboat_getControllerName
, adı başarıyla alırsa PADDLEBOAT_NO_ERROR
hatasını döndürür; aksi takdirde, uygun bir hata kodu döndürülür.
Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
const size_t bufferSize,
char *controllerName);
Parametre | Açıklama |
---|---|
controllerIndex
|
Geri çağırmayı başlatan denetleyicinin dizini. 0 ile arasında bir değer olacaktır PADDLEBOAT_MAX_CONTROLLERS - 1 |
bufferSize
|
controllerName tarafından geçirilen arabelleğin bayt cinsinden boyutu. Ad dizesi, arabelleğe sığması için gerekirse kısaltılır. |
controllerName
|
Denetleyici adının depolanacağı bufferSize baytlık bir arabelleğin işaretçisi. Ad, UTF-8 kodlaması kullanılarak bir C dizesi olarak depolanır. |
Kumanda cihaz bilgileri
Paddleboat_getControllerInfo function
iki giriş parametresi alır: denetleyici dizini ve Paddleboat_Controller_Info
yapısına işaret eden.
Paddleboat_Controller_Info
, verilerle başarılı bir şekilde doldurulduysa Paddleboat_getControllerInfo
, PADDLEBOAT_NO_ERROR
değerini döndürür; aksi takdirde uygun bir hata kodu döndürülür.
Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
Paddleboat_Controller_Info *controllerInfo)
Paddleboat_Controller_Info
yapısı, kumanda hakkında cihaza özel bilgiler içerir.
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;
Denetleyici ile ilişkili InputDevice
öğesinden alınan değerlerle birkaç struct üyesi doldurulur:
controllerNumber - InputDevice.getControllerNumber()
vendorId - InputDevice.getVendorId()
productId - InputDevice.getProductId()
deviceId - InputDevice.getId()
stickFlat
değeri, merkezdeki düz konumun kapsamını temsil eder. Bu değer çoğunlukla kendi kendini ortalayan cihazlarda varsayılan orta "ölü bölge"yi hesaplamak için yararlıdır.stickFuzz
değeri, hata toleransını veya gürültü ve cihaz hassasiyeti sınırlamaları nedeniyle mevcut değerin gerçek değerden ne kadar sapabileceğini gösterir.
Her iki değer de her iki boyutta da maksimum eksen değeri 1.0
olacak şekilde normalleştirilir.
controllerFlags
üyesi, bağımsız bit maskeli işaretlerin ve çoklu bit kombinasyon değerlerinin bir kombinasyonunu içerir.
PADDLEBOAT_CONTROLLER_LAYOUT_MASK
ile mantıksal bir controllerFlags
AND
işlemi uygulandığında, Paddleboat_ControllerButtonLayout
enum'a dönüştürülebilecek bir değer elde edilir. Bu numaralandırma, denetleyici tarafından kullanılan düğme simgesini ve düzenini belirtir.
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
};
Aşağıdaki sabit değerler, özellik bitlerini tanımlar. Bir denetleyicinin belirli bir özelliği destekleyip desteklemediğini belirlemek için controllerFlags
işlevine göre karşılık gelen sabit değer için mantıksal bir AND
işlemi gerçekleştirin. Sonuç sıfır olmayan bir değer, özelliğin denetleyici tarafından desteklendiği anlamına gelir.
PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD
Bu işaret biti ayarlanırsa kumandanın entegre bir dokunmatik alanı vardır. Dokunmatik alana basıldığında kumanda, Paddleboat_Controller_Data.buttonsDown
alanında PADDLEBOAT_BUTTON_TOUCHPAD
bitini ayarlar.
PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE
Bu işaret biti ayarlanırsa kumanda bir işaretçi cihaz emülasyonu yapar. Paddleboat_Controller_Data
yapısının virtualPointer
üyesi, sanal işaretçinin mevcut koordinatlarıyla doldurulur.
Denetleyici verileri
Paddleboat_getControllerData
işlevi iki giriş parametresi alır: denetleyici dizini ve Paddleboat_Controller_Data
yapısına yönelik işaretçi. Paddleboat_Controller_Data
, verilerle başarıyla doldurulursa Paddleboat_getControllerInfo
PADDLEBOAT_NO_ERROR
değerini döndürür; aksi takdirde uygun bir hata kodu döndürülür.
Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
Paddleboat_Controller_Data *controllerData)
Paddleboat_Controller_Data
yapısı, denetleyicinin mevcut kontrol girişi değerlerini içerir.
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;
Değer aralıkları
Giriş türü | Değer aralığı |
---|---|
Kontrol çubuğu ekseni | -1.0 -1.0 |
Tetikleyiciler | 0.0 -1.0 |
Sanal işaretçiler | Pencere genişliği/yüksekliği (piksel cinsinden) için 0.0 |
Yapı ayrıntıları
Üyeyi yapılandırın | Açıklama |
---|---|
buttonsDown
|
Düğme başına bit bit alanı dizisi. Düğme bit maskesi sabitleri, paddlebot.h başlık dosyasında tanımlanır ve PADDLEBOAT_BUTTON_ ile başlar. |
timestamp.
|
En son denetleyici girişi etkinliğinin zaman damgası. Zaman damgası, saat döneminden bu yana geçen mikrosaniyedir. |
virtualPointer
|
Sanal işaretçi konumu. Yalnızca PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE işareti controllerFlags içine ayarlandıysa geçerlidir, aksi takdirde 0.0, 0.0 olur. |