Oyun Kumandası kitaplığını kullanma

Oyun Denetleyici 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ı başlatmak 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
• Türetilmiş bir Context sınıfa jobject JNI nesne referansı. Activity, NativeActivity veya GameActivity dahil ancak bunlarla sınırlı olmamak üzere Context ile türetilmiş herhangi bir sınıf nesnesi geçerlidir.

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

Oyun Kumandası kitaplığının başarıyla başlatılıp başlatılmadığını kontrol etmek için Paddleboat_isInitialized aracını kullanabilirsiniz. Bir boole değeri döndürür. Bu özellik doğruysa API kullanılabilir.

bool Paddleboat_isInitialized()

Uygulamayı sonlandırmadan önce Paddleboat_destroy işlevini kullanarak Oyun Kumandası kitaplığını kapatın. İşlev, tek bir parametreyi (geçerli iş parçacığına ekli bir JNIEnv işaretçisi) alır. Paddleboat_init, Paddleboat_destroy sonra tekrar çağrılabilir.

void Paddleboat_destroy(JNIEnv *env)

Yaşam döngüsü olayları kitaplığını bilgilendirme

Oyun Denetleyicisi 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)

Kumanda 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 işlevini kullanır. Aynı anda yalnızca bir kumanda durumu geri çağırmasını destekler.

• Kumanda durumu geri çağırmasını kaydetmek veya önceden kaydedilmiş geri çağırmaları 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önlendiren isteğe bağlı bir işaretçidir. userData parametresi, geri çağırma işlevine aktarılır. Bu işaretçi, daha sonra Paddleboat_setControllerStatusCallback için yapılan 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ı ş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 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 karesi başına bir kez (tercihen karenin başına yakın yerde) çağrılmalıdır. İşlev, tek bir parametreyi (geçerli iş parçacığına ekli bir JNIEnv işaretçisi) alır.

void Paddleboat_update(JNIEnv *env)

Etkinlikleri işleme

Giriş etkinliklerini aldığında oyununuzun, bunları inceleme için Oyun Denetleyici kitaplığına yönlendirmesi gerekir. Oyun Denetleyici 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 ve etkinlik Oyun Denetleyici kitaplığı tarafından işlenip tüketildiyse 1 değerini döndürür.

GameActivity etkinliğini işleme

Oyununuzda GameActivity kullanılıyorsa Paddleboat_processGameActivityKeyInputEvent veya Paddleboat_processGameActivityMotionInputEvent etkinliği işleme kodunuzdan GameActivityKeyEvent ve GameActivityMotionEvent etkinliklerini 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	Hangi işlevin çağrıldığına bağlı olarak bir GameActivityKeyEvent veya GameActivityMotionEvent yapısına işaret eden öğe.
eventSize	event parametresinde iletilen etkinlik yapısının bayt cinsinden boyutu.

Her iki işlev de etkinlik yoksayıldıysa 0 ve Oyun Denetleyici kitaplığı tarafından işlenip tüketildiyse 1 değerini döndürür.

GameActivity, etkin hareket ekseninin GameActivityPointerAxes_enableAxis işlevi kullanılarak belirtilmesini gerektirir. Paddleboat_getActiveAxisMask çağrısı, bağlı denetleyiciler tarafından kullanılan etkin durumdaki 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;
        }
    }
}

Kumandaları 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ı hakkında veri alır.
• Paddleboat_getControllerData işlevi, kumanda girişlerinin mevcut durumunu alır.

Kumanda adı

Paddleboat_getControllerName function iki giriş parametresi alır: bir denetleyici dizini, bir tampon boyutu ve denetleyici ad dizesini depolayacak bir arabelleğe işaret eden. 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 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çi.

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;

Bazı struct üyeleri, denetleyiciyle ilişkili InputDevice'dan alınan değerlerle 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 esasen kendi kendini ortalayan cihazlarda varsayılan orta "ölü bölge"nin hesaplanmasında 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 farklı olabileceğini temsil eder.

Her iki değer de her iki boyutta da 1.0 olan maksimum eksen değerine normalleştirilir.

controllerFlags üyesi, bağımsız bit maskeli işaretlerin ve birden çok bitli kombinasyon değerlerinin bir kombinasyonunu içerir.

PADDLEBOAT_CONTROLLER_LAYOUT_MASK ile mantıksal bir controllerFlags AND işlemi gerçekleştirildiğinde, Paddleboat_ControllerButtonLayout sıralamasına gönderilebilecek bir değer elde edilir. Bu enum, 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, kapasite 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 olmaması, özelliğin kumanda 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 işaretçi. Paddleboat_Controller_Data, verilerle başarıyla doldurulursa Paddleboat_getControllerInfo PADDLEBOAT_NO_ERROR değerini döndürürse 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ğine (piksel cinsinden) 0.0

Yapı ayrıntıları

Yapı üyesi	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 kumanda giriş 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 politikasında ayarlandıysa geçerlidir; aksi takdirde 0.0, 0.0 değeri kullanılır.