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

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

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

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

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

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

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

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

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

bool Paddleboat_isInitialized()

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

void Paddleboat_destroy(JNIEnv *env)

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

गेम कंट्रोलर लाइब्रेरी को गतिविधि पूरी होने की प्रोसेस 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)

पैरामीटर	ब्यौरा
controllerIndex	कॉलबैक शुरू करने वाले कंट्रोलर का इंडेक्स. यह 0 और के बीच की कोई वैल्यू होगी PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus	PADDLEBOAT_CONTROLLER_JUST_CONNECTED या PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED की Enum वैल्यू.
userData	उपयोगकर्ता के तय किए गए डेटा के लिए, एक वैकल्पिक पॉइंटर (NULL हो सकता है). यह डेटा, Paddleboat_setControllerStatusCallback को किए गए आखिरी कॉल से तय होता है.

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

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

void Paddleboat_update(JNIEnv *env)

इवेंट प्रोसेस करना

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

गेम कंट्रोलर लाइब्रेरी, दो तरह के इनपुट इवेंट के साथ काम करती है: AInputEvents और GameActivity इनपुट इवेंट.

AInputEvent प्रोसेसिंग

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

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

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

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)

पैरामीटर	ब्यौरा
event	GameActivityKeyEvent या GameActivityMotionEvent स्ट्रक्चर का पॉइंटर. यह इस बात पर निर्भर करता है कि किस फ़ंक्शन को कॉल किया जा रहा है.
eventSize	event पैरामीटर में पास किए गए इवेंट स्ट्रक्चर का साइज़, बाइट में.

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

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

uint64_t Paddleboat_getActiveAxisMask()

इसे मैनेज करने का तरीका जानने के लिए, गेम कंट्रोलर लाइब्रेरी का सैंपल देखें. इसमें 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 फ़ंक्शन, तीन इनपुट पैरामीटर लेता है: कंट्रोलर इंडेक्स, बफ़र साइज़, और कंट्रोलर के नाम की स्ट्रिंग को स्टोर करने के लिए बफ़र का पॉइंटर. नाम की स्ट्रिंग को UTF-8 एन्कोडिंग का इस्तेमाल करके, C स्ट्रिंग के तौर पर फ़ॉर्मैट किया जाता है. डिवाइस का नाम, InputDevice.getName() का इस्तेमाल करके इंटरनल तौर पर हासिल किया जाता है.

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

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

पैरामीटर	ब्यौरा
controllerIndex	कॉलबैक शुरू करने वाले कंट्रोलर का इंडेक्स. यह 0 और के बीच की कोई वैल्यू होगी PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize	controllerName से पास किए गए बफ़र का साइज़ बाइट में. अगर बफ़र में फ़िट करने के लिए ज़रूरी हो, तो नाम की स्ट्रिंग को छोटा कर दिया जाएगा.
controllerName	कंट्रोलर का नाम सेव करने के लिए, bufferSize बाइट के बफ़र का पॉइंटर. नाम को UTF-8 एन्कोडिंग का इस्तेमाल करके, C स्ट्रिंग के तौर पर सेव किया जाएगा.

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

Paddleboat_getControllerInfo फ़ंक्शन, दो इनपुट पैरामीटर लेता है: एक कंट्रोलर इंडेक्स और 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 मेंबर में, अलग-अलग बिटमास्क किए गए फ़्लैग और कई बिट वाले कॉम्बिनेशन की वैल्यू का कॉम्बिनेशन होता है.

controllerFlags और PADDLEBOAT_CONTROLLER_LAYOUT_MASK के बीच लॉजिकल 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_getControllerData, 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;

वैल्यू रेंज

इनपुट का टाइप	वैल्यू की सीमा
थंबस्टिक ऐक्सिस	-1.0 से 1.0
ट्रिगर	0.0 से 1.0
वर्चुअल पॉइंटर	0.0 से विंडो की चौड़ाई/ऊंचाई (पिक्सल में)

ध्यान दें: ज़्यादातर कंट्रोलर, L2/R2 बटन की ऐनलॉग रेंज के साथ काम करते हैं. हालांकि, कुछ कंट्रोलर ऐसा नहीं करते. कुछ कंट्रोलर में डिजिटल L2/R2 बटन होते हैं. साथ ही, वे 0.0 या 1.0 रिपोर्ट करते हैं. L1/R1 ट्रिगर आम तौर पर डिजिटल होते हैं और 0.0 या 1.0 की जानकारी देते हैं. हालांकि, अगर कंट्रोलर के साथ काम करता है, तो ऐनलॉग रेंज की जानकारी दी जाती है. ट्रिगर दबाने पर, बटन बिटमास्क भी सेट हो जाएंगे. दूसरे शब्दों में, PADDLEBOAT_BUTTON_L1.

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

होम का सदस्य	ब्यौरा
buttonsDown	बिट-पर-बटन बिटफ़ील्ड कलेक्शन. बटन बिटमास्क कॉन्स्टेंट, paddleboat.h हेडर फ़ाइल में तय किए जाते हैं और PADDLEBOAT_BUTTON_ से शुरू होते हैं.
timestamp	सबसे हाल ही के कंट्रोलर इनपुट इवेंट का टाइमस्टैंप. टाइमस्टैंप, क्लॉक एपोक के बाद से माइक्रोसेकंड में होता है.
virtualPointer	वर्चुअल पॉइंटर की जगह. यह सिर्फ़ तब मान्य होता है, जब PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE फ़्लैग को controllerFlags में सेट किया गया हो. ऐसा न होने पर, यह 0.0, 0.0 होगा.