Oyun Kumandası kitaplığını kullanma

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ıfa jobject JNI nesne referansı. Activity, NativeActivity veya GameActivity 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 veya nullptr 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 bir Paddleboat_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.