গেম কন্ট্রোলার লাইব্রেরি ব্যবহার করা

গেম কন্ট্রোলার লাইব্রেরি ব্যবহার করে আপনার গেমে গেম কন্ট্রোলার সাপোর্ট যোগ করতে নিম্নলিখিত ফাংশন ব্যবহার করুন।

গেম কন্ট্রোলার লাইব্রেরি ইনিশিয়ালাইজ ও ডেস্ট্রয় করা

গেম কন্ট্রোলার লাইব্রেরি ইনিশিয়ালাইজ করতে Paddleboat_init ফাংশন ব্যবহার করুন।

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init দুটি প্যারামিটার নেয়:

• বর্তমান থ্রেডের সাথে অ্যাটাচ করা JNIEnv পয়েন্টার
• jobject JNI অবজেক্ট রেফারেন্স যা Context ডেরিভড ক্লাস। Context থেকে প্রাপ্ত যেকোনও ক্লাস অবজেক্ট বৈধ, যার মধ্যে অন্তর্ভুক্ত হল কিন্তু সীমিত নয় Activity, NativeActivity, বা GameActivity।

ইনিশিয়ালাইজেশন সফল হলে Paddleboat_init রিটার্ন করে PADDLEBOAT_NO_ERROR, অন্যথায় উপযুক্ত সমস্যার কোড রিটার্ন করে।

Game Controller লাইব্রেরি সফলভাবে ইনিশিয়ালাইজ করা হয়েছে কিনা তা চেক করতে আপনি Paddleboat_isInitialized ব্যবহার করতে পারবেন। এটি একটি বুলিয়ান মান রিটার্ন করে। ট্রু হলে, API ব্যবহারের জন্য উপলভ্য।

bool Paddleboat_isInitialized()

অ্যাপ্লিকেশন বন্ধ করার আগে, গেম কন্ট্রোলার লাইব্রেরি বন্ধ করতে Paddleboat_destroy ফাংশন ব্যবহার করুন। এই ফাংশন একটি প্যারামিটার নেয়, যা বর্তমান থ্রেডের সাথে অ্যাটাচ করা JNIEnv-এর পয়েন্টার। Paddleboat_destroy-এর পরে Paddleboat_init-কে আবার ডাকা হতে পারে।

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)

Game Controller লাইব্রেরি আপডেট ফাংশনকে কল করুন

গেম কন্ট্রোলার লাইব্রেরি আপডেট ফাংশন, Paddleboat_update , প্রতিটি গেম ফ্রেম পিছু একবার করে কল করা উচিত, ফ্রেমের শুরুতে কল করলে ভাল হয়। ফাংশনটি একটি প্যারামিটার নেয়, সেটি হল বর্তমান থ্রেডের সাথে অ্যাটাচ করা JNIEnv-এর পয়েন্টার।

void Paddleboat_update(JNIEnv *env)

ইভেন্ট প্রসেস করা

ইনপুট ইভেন্ট পাওয়ার পরে, আপনার গেমকে সেগুলি পরীক্ষা করার জন্য গেম কন্ট্রোলার লাইব্রেরিতে ফরওয়ার্ড করতে হবে। ইনপুট ইভেন্ট তার ম্যানেজ করা ডিভাইসের সাথে যুক্ত কিনা তা Game Controller লাইব্রেরি মূল্যায়ন করে। ম্যানেজ করা ডিভাইস থেকে পাওয়া ইভেন্ট প্রসেস ও ব্যবহার করা হয়।

Game Controller লাইব্রেরি দুই ধরনের ইনপুট ইভেন্ট কাজ করে: AInputEvents এবং GameActivity ইনপুট ইভেন্ট।

AInputEvent প্রসেসিং

আপনার ইভেন্ট হ্যান্ডেলিং কোড থেকে কল করে আপনার গেমকে AInputEvents ফরওয়ার্ড করতে হবে Paddleboat_processInputEvent ।

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)

ইভেন্ট উপেক্ষা করা হলে দুটি ফাংশনই 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 function দুটি ইনপুট প্যারামিটার নেয়: একটি কন্ট্রোলার ইনডেক্স, একটি বাফার সাইজ এবং কন্ট্রোলারের নাম স্টোর করার জন্য একটি বাফারের পয়েন্টার। UTF-8 এনকোডিং ব্যবহার করে নামের স্ট্রিংটিকে a 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 মেম্বারে বিটমাস্ক করা ফ্ল্যাগ ও একাধিক বিট কম্বিনেশন ভ্যালুর কম্বিনেশন থাকে।

controllerFlags-এর সাথে লজিক্যাল AND পারফর্ম করলে PADDLEBOAT_CONTROLLER_LAYOUT_MASK এমন একটি ভ্যালু পাওয়া যায় যা Paddleboat_ControllerButtonLayout এনামে কাস্ট করা যেতে পারে। এই এনুম কন্ট্রোলার দ্বারা ব্যবহৃত বোতাম আইকনোগ্রাফি ও লেআউট নির্দিষ্ট করে।

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;

ভ্যালুর রেঞ্জ

স্ট্রাকচার সংক্রান্ত বিবরণ