गेम कंट्रोलर लाइब्रेरी का इस्तेमाल करना

Game Controller लाइब्रेरी का इस्तेमाल करके, अपने गेम में गेम कंट्रोलर की सुविधा जोड़ने के लिए, इन फ़ंक्शन का इस्तेमाल करें.

गेम कंट्रोलर लाइब्रेरी को शुरू और बंद करना

गेम कंट्रोलर लाइब्रेरी को शुरू करने के लिए, Paddleboat_init फ़ंक्शन का इस्तेमाल करें.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init में दो पैरामीटर होते हैं:

• मौजूदा थ्रेड से अटैच किए गए JNIEnv का पॉइंटर
• jobject, Context से मिली क्लास का JNI ऑब्जेक्ट रेफ़रंस है. Context से मिली किसी भी क्लास का ऑब्जेक्ट मान्य होता है. इसमें इनके अलावा, और भी ऑब्जेक्ट शामिल हो सकते हैं: Activity, NativeActivity, या GameActivity.

अगर शुरू करने की प्रोसेस पूरी हो जाती है, तो Paddleboat_init, PADDLEBOAT_NO_ERROR दिखाता है. ऐसा न होने पर, गड़बड़ी का सही कोड दिखाता है.

Paddleboat_isInitialized का इस्तेमाल करके, यह देखा जा सकता है कि GameController लाइब्रेरी सही तरीके से शुरू हुई है या नहीं. यह बूलियन वैल्यू दिखाता है. अगर वैल्यू सही है, तो एपीआई का इस्तेमाल किया जा सकता है.

bool Paddleboat_isInitialized()

ऐप्लिकेशन बंद करने से पहले, Paddleboat_destroy फ़ंक्शन का इस्तेमाल करके, गेम कंट्रोलर लाइब्रेरी को बंद करें. यह फ़ंक्शन एक पैरामीटर लेता है, जो मौजूदा थ्रेड से जुड़े JNIEnv का पॉइंटर होता है. Paddleboat_init को Paddleboat_destroy के बाद फिर से कॉल किया जा सकता है.

void Paddleboat_destroy(JNIEnv *env)

लाइब्रेरी को लाइफ़साइकल इवेंट की सूचना देना

Game Controller library को activity lifecycle onStop और onStart इवेंट के बारे में जानकारी देनी होगी. स्टॉप और स्टार्ट इवेंट हैंडलिंग कोड से, Paddleboat_onStop और Paddleboat_onStart फ़ंक्शन को कॉल करें. दोनों फ़ंक्शन एक पैरामीटर लेते हैं: मौजूदा थ्रेड से जुड़े JNIEnv का पॉइंटर.

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

कंट्रोलर की स्थिति के बारे में सूचना देने वाले कॉलबैक को रजिस्टर करना या हटाना

गेम कंट्रोलर लाइब्रेरी, कंट्रोलर की स्थिति के बारे में सूचना देने के लिए कंट्रोलर स्टेटस कॉलबैक का इस्तेमाल करती है. इससे गेम को यह सूचना मिलती है कि कंट्रोलर कनेक्ट या डिसकनेक्ट हो गया है. यह एक समय में सिर्फ़ एक कंट्रोलर के स्टेटस के बारे में सूचना देने वाले कॉलबैक के साथ काम करता है.

• कंट्रोलर के स्टेटस के कॉलबैक को रजिस्टर करने या पहले से रजिस्टर किए गए किसी कॉलबैक को नए कॉलबैक फ़ंक्शन से बदलने के लिए, Paddleboat_setControllerStatusCallback फ़ंक्शन को कॉल करें.
• मौजूदा समय में रजिस्टर किए गए किसी भी कॉलबैक को हटाने के लिए, NULL या nullptr पास करें.
• userData पैरामीटर, उपयोगकर्ता की ओर से तय किए गए डेटा का वैकल्पिक पॉइंटर होता है. userData पैरामीटर को कॉलबैक फ़ंक्शन में पास किया जाएगा. इस पॉइंटर को आंतरिक तौर पर तब तक सेव रखा जाता है, जब तक कि Paddleboat_setControllerStatusCallback को बाद में कॉल करके इसे बदला नहीं जाता.

void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

कॉलबैक फ़ंक्शन का फ़ंक्शन सिग्नेचर यह है:

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

गेम कंट्रोलर लाइब्रेरी के अपडेट फ़ंक्शन को कॉल करें

गेम कंट्रोलर लाइब्रेरी के अपडेट फ़ंक्शन, Paddleboat_update को हर गेम फ़्रेम में एक बार कॉल किया जाना चाहिए. बेहतर होगा कि इसे फ़्रेम की शुरुआत में कॉल किया जाए. यह फ़ंक्शन एक पैरामीटर लेता है, जो मौजूदा थ्रेड से जुड़े JNIEnv का पॉइंटर होता है.

void Paddleboat_update(JNIEnv *env)

प्रोसेस इवेंट

इनपुट इवेंट मिलने पर, आपके गेम को उन्हें Game Controller library को भेजना होगा, ताकि उनकी जांच की जा सके. गेम कंट्रोलर लाइब्रेरी यह पता लगाती है कि क्या कोई इनपुट इवेंट, मैनेज किए जा रहे किसी डिवाइस से जुड़ा है. मैनेज किए जा रहे डिवाइसों से मिले इवेंट प्रोसेस किए जाते हैं और उनका इस्तेमाल किया जाता है.

Game Controller library, दो तरह के इनपुट इवेंट के साथ काम करती है: AInputEvents और GameActivity इनपुट इवेंट.

AInputEvent प्रोसेसिंग

आपका गेम, इवेंट हैंडलिंग कोड से Paddleboat_processInputEvent को कॉल करके AInputEvents फ़ॉरवर्ड करे.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

अगर इवेंट को अनदेखा किया गया था, तो Paddleboat_processInputEvent दिखेगा. अगर इवेंट को Game Controller लाइब्रेरी ने प्रोसेस किया था और इस्तेमाल किया था, तो 1 दिखेगा.0

GameActivity इवेंट प्रोसेसिंग

अगर आपका गेम GameActivity का इस्तेमाल करता है, तो इवेंट हैंडलिंग कोड से Paddleboat_processGameActivityKeyInputEvent या Paddleboat_processGameActivityMotionInputEvent को कॉल करके, GameActivityKeyEvent और GameActivityMotionEvent इवेंट फ़ॉरवर्ड करें.

int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
                                                    const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
                                                       const size_t eventSize)

अगर इवेंट को अनदेखा किया गया है, तो दोनों फ़ंक्शन 0 दिखाएंगे. अगर इवेंट को Game Controller लाइब्रेरी ने प्रोसेस किया है और उसका इस्तेमाल किया है, तो दोनों फ़ंक्शन 1 दिखाएंगे.

GameActivity के लिए, GameActivityPointerAxes_enableAxis फ़ंक्शन का इस्तेमाल करके, मोशन ऐक्सिस को चालू करना ज़रूरी है. Paddleboat_getActiveAxisMask कॉल, कनेक्ट किए गए कंट्रोलर के ज़रिए इस्तेमाल किए जा रहे मोशन ऐक्सिस का बिटमास्क दिखाता है.

uint64_t Paddleboat_getActiveAxisMask()

इसे मैनेज करने के तरीके का उदाहरण देखने के लिए, Game Controller library का वह सैंपल देखें जिसमें GameActivity का इस्तेमाल किया गया है. यह सैंपल, ऐक्टिव ऐक्सिस मास्क की पोलिंग करता है और नए ऐक्सिस इस्तेमाल किए जाने पर GameActivity को सूचना देता है. इसे 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;
        }
    }
}

कंट्रोलर के बारे में जानकारी पाना

गेम कंट्रोलर लाइब्रेरी, किसी कंट्रोलर को रेफ़र करने के लिए इंडेक्स वैल्यू का इस्तेमाल करती है. मान्य इंडेक्स वैल्यू की रेंज 0 से PADDLEBOAT_MAX_CONTROLLERS - 1 तक होती है. Paddleboat_getControllerStatus फ़ंक्शन से, किसी कंट्रोलर इंडेक्स की स्थिति का पता चलता है.

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

कनेक्ट किए गए कंट्रोलर से जानकारी पढ़ने के लिए, तीन फ़ंक्शन उपलब्ध हैं.

• Paddleboat_getControllerName फ़ंक्शन, कंट्रोलर डिवाइस का नाम वापस लाता है.
• Paddleboat_getControllerInfo फ़ंक्शन, कंट्रोलर डिवाइस के बारे में डेटा वापस लाता है.
• Paddleboat_getControllerData फ़ंक्शन, कंट्रोलर इनपुट की मौजूदा स्थिति को वापस लाता है.

कंट्रोलर का नाम

Paddleboat_getControllerName function फ़ंक्शन में दो इनपुट पैरामीटर होते हैं: कंट्रोलर इंडेक्स, बफ़र का साइज़, और कंट्रोलर के नाम की स्ट्रिंग को सेव करने के लिए बफ़र का पॉइंटर. नाम वाली स्ट्रिंग को UTF-8 एन्कोडिंग का इस्तेमाल करके, C स्ट्रिंग के तौर पर फ़ॉर्मैट किया जाता है. डिवाइस का नाम, InputDevice.getName() का इस्तेमाल करके अंदरूनी तौर पर हासिल किया जाता है.

अगर Paddleboat_getControllerName फ़ंक्शन नाम को वापस पाने में सफल होता है, तो यह PADDLEBOAT_NO_ERROR दिखाता है. ऐसा न होने पर, यह गड़बड़ी का सही कोड दिखाता है.

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

कंट्रोलर डिवाइस की जानकारी

Paddleboat_getControllerInfo function फ़ंक्शन दो इनपुट पैरामीटर लेता है: कंट्रोलर इंडेक्स और Paddleboat_Controller_Info स्ट्रक्चर का पॉइंटर.

अगर Paddleboat_Controller_Info में डेटा सही तरीके से भर दिया गया है, तो Paddleboat_getControllerInfo, PADDLEBOAT_NO_ERROR दिखाता है. ऐसा न होने पर, गड़बड़ी का सही कोड दिखता है.

Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

Paddleboat_Controller_Info स्ट्रक्चर में, कंट्रोलर के बारे में डिवाइस के हिसाब से जानकारी होती है.

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;

कई स्ट्रक्चर मेंबर में, कंट्रोलर से जुड़े InputDevice से ली गई वैल्यू भरी जाती हैं:

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

• stickFlat वैल्यू से पता चलता है कि सेंटर फ़्लैट की पोज़िशन कितनी है. यह वैल्यू मुख्य रूप से, अपने-आप सेंटर में आने वाले डिवाइसों पर डिफ़ॉल्ट सेंटर 'डेड-ज़ोन' का हिसाब लगाने के लिए काम आती है.
• stickFuzz वैल्यू, गड़बड़ी को बर्दाश्त करने की क्षमता को दिखाती है. इसका मतलब है कि नॉइज़ और डिवाइस की संवेदनशीलता की सीमाओं की वजह से, मौजूदा वैल्यू, असल वैल्यू से कितनी अलग हो सकती है.

दोनों वैल्यू को किसी भी डाइमेंशन में, 1.0 की ज़्यादा से ज़्यादा ऐक्सिस वैल्यू के हिसाब से सामान्य किया जाता है.

controllerFlags सदस्य में, अलग-अलग बिटमास्क वाले फ़्लैग और एक से ज़्यादा बिट वाले कॉम्बिनेशन की वैल्यू शामिल होती हैं.

PADDLEBOAT_CONTROLLER_LAYOUT_MASK के साथ controllerFlags का लॉजिकल AND करने पर, ऐसी वैल्यू मिलती है जिसे Paddleboat_ControllerButtonLayout enum में कास्ट किया जा सकता है. इस enum से, कंट्रोलर के इस्तेमाल किए गए बटन के आइकॉन और लेआउट के बारे में पता चलता है.

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
};

यहां दिए गए कॉन्स्टेंट, क्षमता के बिट तय करते हैं. यह पता लगाने के लिए कि कोई कंट्रोलर किसी सुविधा के साथ काम करता है या नहीं, controllerFlags के साथ उससे जुड़े कॉन्स्टेंट का लॉजिकल AND करें. अगर नतीजे में शून्य के अलावा कोई और संख्या दिखती है, तो इसका मतलब है कि कंट्रोलर में यह सुविधा काम करती है.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

अगर यह फ़्लैग बिट सेट है, तो कंट्रोलर में इंटिग्रेटेड टचपैड होता है. अगर टचपैड को दबाया जाता है, तो कंट्रोलर Paddleboat_Controller_Data.buttonsDown फ़ील्ड में PADDLEBOAT_BUTTON_TOUCHPAD बिट सेट करता है.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

अगर यह फ़्लैग बिट सेट है, तो कंट्रोलर एक पॉइंटर डिवाइस की तरह काम करता है. Paddleboat_Controller_Data स्ट्रक्चर का virtualPointer सदस्य, वर्चुअल पॉइंटर के मौजूदा कोऑर्डिनेट से भर जाता है.

कंट्रोलर का डेटा

Paddleboat_getControllerData फ़ंक्शन में दो इनपुट पैरामीटर होते हैं: कंट्रोलर इंडेक्स और Paddleboat_Controller_Data स्ट्रक्चर का पॉइंटर. अगर Paddleboat_Controller_Data में डेटा सही तरीके से भर दिया जाता है, तो Paddleboat_getControllerInfo, PADDLEBOAT_NO_ERROR दिखाता है. ऐसा न होने पर, गड़बड़ी का सही कोड दिखता है.

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

Paddleboat_Controller_Data स्ट्रक्चर में कंट्रोलर के मौजूदा कंट्रोल इनपुट की वैल्यू शामिल होती हैं.

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;

वैल्यू की रेंज

स्ट्रक्चर की जानकारी