استفاده از کتابخانه «کنترل‌کننده بازی»

از توابع زیر برای افزودن پشتیبانی از کنترل‌کننده بازی به بازی‌تان بااستفاده از کتابخانه «کنترل‌کننده بازی» استفاده کنید.

راه‌اندازی و ازبین بردن کتابخانه «کنترل‌کننده بازی»

از تابع 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 را برمی‌گرداند، درغیراین‌صورت کد خطای مناسبی برگردانده می‌شود.

می‌توانید از 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)

فراخوانی تابع به‌روزرسانی کتابخانه «کنترل‌کننده بازی»

تابع به‌روزرسانی کتابخانه «کنترل‌کننده بازی»، 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 استفاده می‌کند، رویدادهای GameActivityKeyEvent و GameActivityMotionEvent را با فراخوانی Paddleboat_processGameActivityKeyInputEvent یا Paddleboat_processGameActivityMotionInputEvent از کد مدیریت رویداد ارسال کنید.

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 دو پارامتر ورودی می‌گیرد: شاخص کنترل‌کننده، اندازه بافر، و اشاره‌گری به بافری برای ذخیره کردن رشته نام کنترل‌کننده. رشته نام به‌عنوان رشته C بااستفاده از کدبندی UTF-8 قالب‌بندی می‌شود. نام دستگاه به‌صورت داخلی بااستفاده از 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 شامل ترکیبی از پرچم‌های ماسک‌شده بیتی فردی و مقادیر ترکیبی چند بیتی است.

انجام AND منطقی controllerFlags با 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
};

ثابت‌های زیر بیت‌های قابلیت را تعریف می‌کنند. برای تعیین اینکه کنترل‌کننده از قابلیت خاصی پشتیبانی می‌کند یا نه، AND منطقی ثابت مربوطه را دربرابر controllerFlags انجام دهید. نتیجه غیرصفر یعنی کنترل‌کننده از این قابلیت پشتیبانی می‌کند.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

اگر این بیت پرچم تنظیم شده باشد، کنترل‌کننده صفحه لمسی یکپارچه دارد. اگر صفحه لمسی فشار داده شود، کنترل‌کننده بیت PADDLEBOAT_BUTTON_TOUCHPAD را در فیلد Paddleboat_Controller_Data.buttonsDown تنظیم می‌کند.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

اگر این بیت پرچم تنظیم شده باشد، کنترل‌کننده دستگاه اشاره‌گر را شبیه‌سازی می‌کند. عضو virtualPointer ساختار Paddleboat_Controller_Data با مختصات کنونی اشاره‌گر مجازی تکمیل می‌شود.

داده‌های کنترل‌کننده

تابع 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;

محدوده‌های مقدار

جزئیات ساختار