שימוש בספרייה של בקר המשחקים

אפשר להשתמש בפונקציות הבאות כדי להוסיף למשחק תמיכה בבקר משחקים באמצעות הספרייה של בקר המשחקים.

אתחול והשמדה של ספריית בקר המשחקים

שימוש בPaddleboat_init לאתחול הספרייה של בקר המשחקים.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

הפונקציה Paddleboat_init לוקחת שני פרמטרים:

• מצביע אל JNIEnv מצורף לשרשור הנוכחי
• הפניה של אובייקט JNI מסוג jobject אל המחלקה נגזרת Context. כל Context אובייקט המחלקה הנגזר חוקי, כולל, בין היתר Activity, NativeActivity, או GameActivity.

אפשרות החזרה במחיר Paddleboat_init PADDLEBOAT_NO_ERROR אם האתחול בוצע בהצלחה, אחרת קוד שגיאה מתאים מוחזר.

אפשר להשתמש ב-Paddleboat_isInitialized כדי לבדוק אם המשחק ספריית הבקר אותחלה בהצלחה. הפונקציה מחזירה ערך בוליאני עם ערך מסוים. אם הערך הוא True, ה-API זמין לשימוש.

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)

רישום או הסרה של קריאה חוזרת (callback) של סטטוס הבקר

הספרייה של בקר המשחקים משתמשת בקריאה חוזרת (callback) של סטטוס הבקר כדי לשלוח התראות לגבי משחק כשבקר מחובר או מנותק. הוא תומך בבקר אחד בלבד את הקריאה החוזרת (callback) של הסטטוס.

• כדי לרשום קריאה חוזרת (callback) של סטטוס בקר או להחליף כל הגדרה קודמת קריאה חוזרת (callback) רשומה עם פונקציית קריאה חוזרת חדשה, מפעילים את הפונקציה Paddleboat_setControllerStatusCallback.
• כדי להסיר קריאה חוזרת (callback) שרשומה כרגע, צריך להעביר את 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	הערך של הטיפוס בן המנייה (enum) של PADDLEBOAT_CONTROLLER_JUST_CONNECTED או PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED.
userData	מצביע אופציונלי (יכול להיות NULL) למשתמש נתונים מוגדרים שצוינו על ידי הקריאה האחרונה ל- Paddleboat_setControllerStatusCallback

קריאה לפונקציית העדכון של ספריית בקר המשחקים

פונקציית העדכון של ספריית בקר המשחקים, Paddleboat_update , צריך לקרוא פעם אחת לכל פריים במשחק, עדיף בתחילת הפריים. הפונקציה לוקחת פרמטר יחיד, מצביע אל JNIEnv שמצורף אל השרשור הנוכחי.

void Paddleboat_update(JNIEnv *env)

אירועים בתהליך

כשמקבלים אירועי קלט, המשחק צריך להעביר אותם לספרייה של בקר המשחקים לצורך בדיקה. לשלט לגיימינג הספרייה בוחנת אם אירוע קלט משויך לאחד מהאירועים המנוהלים מכשירים. אירועים ממכשירים מנוהלים מעובדים ונצרכים.

הספרייה של בקר המשחקים תומכת בשני סוגים של אירועי קלט: AInputEvents ו- GameActivity אירועי קלט.

עיבוד AInputEvent

עליך להתקשר אל AInputEvents כדי להעביר את המשחק Paddleboat_processInputEvent מקוד הטיפול באירועים.

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)

פרמטר	תיאור
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 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);

פרמטר	תיאור
controllerIndex	האינדקס של הבקר שביצע את קריאה חוזרת. יהיה ערך בין 0 ל- PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize	גודל בבייטים של מאגר הנתונים הזמני controllerName, מחרוזת השם תהיה. נקטע אם צריך כדי לאפשר התאמה למאגר הנתונים הזמני.
controllerName	מצביע למאגר נתונים זמני של bufferSize בייטים כדי לאחסן את שם הבקר. השם יקבל יישמרו כמחרוזת C בקידוד UTF-8.

מידע על מכשירי השלט רחוק

הפונקציה 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;

חלק מחברי ה-Build מאוכלסים בערכים שנלקחים מה 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). ה-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
};

הקבועים הבאים מגדירים ביטים של יכולות. כדי לבדוק אם שלט רחוק תומך ביכולת מסוימת, לבצע 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;

טווחי ערכים

סוג קלט	טווח ערכים
ציר של מתאם לאגודל	-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	מערך שדה סיביות של Bit-per-button. מסכת ביט של לחצן קבועים מוגדרים ב-paddleboat.h. את קובץ הכותרת, ולהתחיל ב- PADDLEBOAT_BUTTON_.
timestamp.	חותמת הזמן של קלט השלט רחוק האחרון אירוע. חותמת הזמן היא במיליוניות השנייה מאז פרק זמן של שעון.
virtualPointer	מיקום הסמן הווירטואלי. תקף רק אם דגל PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE מוגדר ב-controllerFlags, אחרת יהיה 0.0, 0.0.