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 kumandası kitaplığını başlatma ve yok etme

Game Controller kitaplığını başlatmak için Paddleboat_init işlevini kullanın.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init iki parametre alır:

• Geçerli ileti dizisine eklenmiş bir JNIEnv işaretçisi
• Context türetilmiş sınıfına yönelik bir jobject JNI nesne referansı. Context türetilmiş sınıf nesneleri (Activity, NativeActivity veya GameActivity dahil ancak bunlarla sınırlı olmamak üzere) geçerlidir.

Başlatma başarılıysa Paddleboat_init, PADDLEBOAT_NO_ERROR değerini, aksi takdirde uygun bir hata kodunu döndürür.

GameController kitaplığının başarıyla başlatılıp başlatılmadığını kontrol etmek için Paddleboat_isInitialized kullanabilirsiniz. Boole değeri döndürür. Doğruysa API kullanılabilir.

bool Paddleboat_isInitialized()

Uygulamayı sonlandırmadan önce, Oyun Kumandası kitaplığını kapatmak için Paddleboat_destroy işlevini kullanın. İşlev, tek bir parametre alır: mevcut işleme eklenmiş bir JNIEnv işaretçisi. Paddleboat_init, Paddleboat_destroy tarihinden sonra tekrar aranabilir.

void Paddleboat_destroy(JNIEnv *env)

Kitaplığı yaşam döngüsü etkinlikleri hakkında bilgilendirme

Oyun kumandası kitaplığı, etkinlik yaşam döngüsü onStop ve onStart etkinlikleri hakkında bilgilendirilmelidir. Durdurma ve başlatma 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şleme eklenmiş bir JNIEnv işaretçisi.

void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)

Denetleyici durumu geri arama kaydetme veya kaldırma

Game Controller kitaplığı, bir kumanda bağlandığında veya bağlantısı kesildiğinde oyunu bilgilendirmek için kumanda durumu geri çağırmasını kullanır. Aynı anda yalnızca bir denetleyici durumu geri çağırmasını destekler.

• Bir denetleyici durumu geri çağırmasını kaydetmek veya daha önce kaydedilmiş bir geri çağırmayı yeni bir geri çağırma işleviyle değiştirmek için Paddleboat_setControllerStatusCallback işlevini çağırın.
• Kayıtlı geri aramaları kaldırmak için NULL veya nullptr değerini iletin.
• userData parametresi, kullanıcı tarafından tanımlanan verilere yönelik isteğe bağlı bir işaretçidir. userData parametresi, geri çağırma işlevine iletilir. Bu işaretçi, Paddleboat_setControllerStatusCallback için yapılan sonraki bir çağrı ile değiştirilene kadar dahili olarak saklanır.

void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

Geri çağırma işlevinin işlev imzası şöyledir:

typedef void (*Paddleboat_ControllerStatusCallback)(
  const int32_t controllerIndex,
  const Paddleboat_ControllerStatus controllerStatus,
  void *userData)

Parametre	Açıklama
controllerIndex	Geri aramayı başlatan denetleyicinin dizini. 0 ile arasında bir değer olur. PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus	PADDLEBOAT_CONTROLLER_JUST_CONNECTED veya PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED numaralandırma değeri.
userData	Paddleboat_setControllerStatusCallback işlevine yapılan son çağrıyla belirtilen, kullanıcı tanımlı verilere yönelik isteğe bağlı bir işaretçi (NULL olabilir).

Oyun kumandası kitaplığı güncelleme işlevini çağırma

Oyun Kumandası kitaplığı güncelleme işlevi, Paddleboat_update , oyun çerçevesi başına bir kez, tercihen çerçevenin başlangıcına yakın bir yerde çağrılmalıdır. İşlev, tek bir parametre alır: mevcut işleme eklenmiş bir JNIEnv işaretçisi.

void Paddleboat_update(JNIEnv *env)

Etkinlikleri işleme

Oyununuz, giriş etkinliklerini aldığında inceleme için Game Controller kitaplığına yönlendirmelidir. Game Controller kitaplığı, bir giriş etkinliğinin yönetilen cihazlarından biriyle ilişkili olup olmadığını değerlendirir. Yönetilen cihazlardaki etkinlikler işlenir ve kullanılır.

Game Controller kitaplığı iki tür giriş etkinliğini destekler: AInputEvents ve GameActivity giriş etkinlikleri.

AInputEvent işleme

Oyununuz, etkinlik işleme kodunuzdan Paddleboat_processInputEvent'ı çağırarak AInputEvents değerini iletmelidir.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

Etkinlik yok sayıldıysa Paddleboat_processInputEvent, etkinlik işlenip Game Controller kitaplığı tarafından kullanıldıysa 0 döndürülür. 1

GameActivity etkinlik işleme

Oyununuzda GameActivity kullanılıyorsa GameActivityKeyEvent ve GameActivityMotionEvent etkinliklerini, etkinlik işleme kodunuzdan Paddleboat_processGameActivityKeyInputEvent veya Paddleboat_processGameActivityMotionInputEvent'yi çağırarak iletin.

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	Hangi işlevin çağrıldığına bağlı olarak GameActivityKeyEvent veya GameActivityMotionEvent yapısına yönelik bir işaretçi.
eventSize	event parametresinde iletilen etkinlik yapısının bayt cinsinden boyutu.

Her iki işlev de etkinlik yoksayıldıysa 0, etkinlik işlenip Game Controller kitaplığı tarafından kullanıldıysa 1 değerini döndürür.

GameActivity, GameActivityPointerAxes_enableAxis işlevi kullanılarak etkin hareket ekseninin belirtilmesini gerektirir. Paddleboat_getActiveAxisMask çağrısı, bağlı kontrol cihazları tarafından kullanılan, şu anda etkin olan hareket eksenlerinin bit maskesini döndürür.

uint64_t Paddleboat_getActiveAxisMask()

Bunun nasıl ele alınacağına dair bir örnek için GameActivity kullanan Game Controller kitaplığı örneğine bakın. Örnek, etkin eksen maskesini yoklar ve yeni eksenler kullanıldığında GameActivity bilgisini 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;
        }
    }
}

Okuma denetleyicileri

Oyun kumandası kitaplığı, belirli bir kumandayı ifade etmek için bir dizin değeri kullanır. Geçerli dizin değerleri 0 ile PADDLEBOAT_MAX_CONTROLLERS - 1 arasında değişir. 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 vardır.

• Paddleboat_getControllerName işlevi, denetleyici cihazın adını alır.
• Paddleboat_getControllerInfo işlevi, denetleyici cihazın kendisiyle ilgili verileri alır.
• Paddleboat_getControllerData işlevi, kumanda girişlerinin mevcut durumunu alır.

Denetleyici adı

Paddleboat_getControllerName function iki giriş parametresi alır: denetleyici dizini, arabellek boyutu ve denetleyici adı dizesini depolayacak bir arabelleğe yönelik 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 değerini, aksi takdirde uygun bir hata kodunu döndürür.

Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
                                                  const size_t bufferSize,
                                                  char *controllerName);

Parametre	Açıklama
controllerIndex	Geri aramayı başlatan denetleyicinin dizini. 0 ile arasında bir değer olur. PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize	controllerName tarafından iletilen 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ğe yönelik işaretçi. Ad, UTF-8 kodlaması kullanılarak C dizesi olarak saklanır.

Kontrol cihazı bilgileri

Paddleboat_getControllerInfo function, iki giriş parametresi alır: bir denetleyici dizini ve bir Paddleboat_Controller_Info yapısına yönelik işaretçi.

Paddleboat_Controller_Info 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_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

Paddleboat_Controller_Info yapısı, kontrol cihazıyla ilgili cihaza özel bilgileri 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;

Birkaç yapı üyesi, denetleyiciyle ilişkili InputDevice öğesinden alınan değerlerle doldurulur:

controllerNumber    -   InputDevice.getControllerNumber()
vendorId              - InputDevice.getVendorId()
productId             - InputDevice.getProductId()
deviceId              - InputDevice.getId()

• stickFlat değeri, merkez düz konumunun kapsamını gösterir. Bu değer, özellikle kendi kendini merkezleyen cihazlarda varsayılan bir merkez "ölü bölge" hesaplamak için kullanışlıdır.
• stickFuzz değeri, hata toleransını veya mevcut değerin gürültü ve cihaz hassasiyeti sınırlamaları nedeniyle gerçek değerden ne kadar sapabileceğini gösterir.

Her iki değer de her iki boyutta 1.0 maksimum eksen değerine göre normalleştirilir.

controllerFlags üyesi, tek tek bit maskeli işaretlerin ve çok bitli kombinasyon değerlerinin bir kombinasyonunu içeriyor.

controllerFlags ile PADDLEBOAT_CONTROLLER_LAYOUT_MASK üzerinde mantıksal AND işlemi yapıldığında, Paddleboat_ControllerButtonLayout enum'ına yayınlanabilecek bir değer elde edilir. Bu enum, denetleyici tarafından kullanılan düğme ikonografisini 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 sabitler, özellik bitlerini tanımlar. Bir denetleyicinin belirli bir özelliği destekleyip desteklemediğini belirlemek için ilgili sabitin AND ile controllerFlags arasında mantıksal bir işlem yapın. Sıfır olmayan bir sonuç, özelliğin kontrol cihazı tarafından desteklendiği anlamına gelir.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

Bu işaret biti ayarlanırsa kumandada entegre dokunmatik alan bulunur. Dokunmatik yüzeye 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 denetleyici bir işaretçi cihazı taklit eder. Paddleboat_Controller_Data yapısının virtualPointer üyesi, sanal işaretçinin geçerli koordinatlarıyla doldurulur.

Denetleyici verileri

Paddleboat_getControllerData işlevi iki giriş parametresi alır: bir denetleyici dizini ve bir 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ı, kontrol cihazının mevcut kontrol giriş 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ığı
Oyun çubuğu ekseni	-1.0-1.0
Tetikleyiciler	0.0-1.0
Sanal işaretçiler	0.0 ila pencere genişliği/yüksekliği (piksel cinsinden)

Not: L2/R2 düğmesi analog aralıkları çoğu kumanda tarafından desteklenir ancak bazı kumandalar tarafından desteklenmez. Bazı denetleyicilerde dijital L2/R2 düğmeleri bulunur ve 0.0 veya 1.0 bildirilir. L1/R1 tetikleyicileri genellikle dijitaldir ve 0.0 veya 1.0 olarak raporlanır. Bununla birlikte, kontrol cihazı tarafından destekleniyorsa analog aralıklar raporlanır. Tetikleyiciler, basıldığında düğme bit maskelerini de ayarlar (diğer bir deyişle PADDLEBOAT_BUTTON_L1).

Yapı ayrıntıları

Yapı üyesi	Açıklama
buttonsDown	Bit-per-button bitfield array. Düğme bit maskesi sabitleri paddleboat.h. başlık dosyasında tanımlanır ve PADDLEBOAT_BUTTON_ ile başlar.
timestamp.	En son kontrol cihazı giriş etkinliğinin zaman damgası. Zaman damgası, saat epoch'undan bu yana geçen mikro saniyedir.
virtualPointer	Sanal işaretçi konumu. Yalnızca controllerFlags içinde PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE işareti ayarlanırsa geçerlidir, aksi takdirde 0.0, 0.0 olur.