הוספת תמיכה במכשירי עכבר

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

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

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

• כדי לרשום קריאה חוזרת (callback) לסטטוס העכבר או להחליף קריאה חוזרת רשומה קודמת בפונקציית קריאה חוזרת חדשה, קוראים לפונקציה Paddleboat_setMouseStatusCallback.
• כדי להסיר קריאה חוזרת שרשומה כרגע, מעבירים את הערך NULL או nullptr בפרמטר statusCallback.
• הפרמטר userData הוא מצביע אופציונלי לנתונים שהוגדרו על ידי המשתמש. הפרמטר userData יועבר לפונקציית הקריאה החוזרת. הסמן הזה נשמר באופן פנימי עד שמשנים אותו באמצעות קריאה אחרת ל-Paddleboat_setMouseStatusCallback.

void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
  statusCallback, void *userData)

חתימת הפונקציה של פונקציית הקריאה החוזרת של סטטוס העכבר היא:

typedef void (*Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus
  mouseStatus, void *userData)

לפרמטר mouseStatus enum יש שלושה ערכים אפשריים:

• ‫PADDLEBOAT_MOUSE_NONE: אין כרגע מכשיר עכבר מחובר.
• PADDLEBOAT_MOUSE_CONTROLLER_EMULATED: בקר מחובר מדמה עכבר.
• ‫PADDLEBOAT_MOUSE_PHYSICAL: מחוברים מכשיר עכבר פיזי אחד או יותר. (המכשירים האלה כוללים עכבר, לוח מגע, כדור עקיבה או מכשירים דומים אחרים).

הפרמטר userData מכיל את מצביע userData שצוין בקריאה האחרונה אל Paddleboat_setMouseStatusCallback. הערך של userData יכול להיות NULL או nullptr.

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

הספרייה Game Controller מדווחת נתונים רק ממכשיר עכבר יחיד. למכשירי עכבר פיזיים יש עדיפות על פני מכשירי עכבר של בקר וירטואלי. אם מחובר עכבר פיזי, הוא יחליף את העכבר של בקר וירטואלי שהיה פעיל קודם.

קריאת נתוני העכבר

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

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

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

bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

המבנה Paddleboat_Mouse_Data מכיל מידע על:

• חותמת הזמן של אירוע הקלט האחרון של העכבר
• המיקום הנוכחי של הסמן
• סטטוס של כפתורי העכבר
• סטטוס גלגלי העכבר

struct Paddleboat_Mouse_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    int32_t mouseScrollDeltaH;
    int32_t mouseScrollDeltaV;
    float mouseX;
    float mouseY;
}

ספריית בקר המשחקים מגדירה קבועים של מסכות ביטים ללחצני העכבר בקובץ הכותרת של הממשק paddleboat.h:

enum Paddleboat_Mouse_Buttons {
    PADDLEBOAT_MOUSE_BUTTON_LEFT = (1U << 0),
    PADDLEBOAT_MOUSE_BUTTON_RIGHT = (1U << 1),
    PADDLEBOAT_MOUSE_BUTTON_MIDDLE = (1U << 2),
    PADDLEBOAT_MOUSE_BUTTON_BACK = (1U << 3),
    PADDLEBOAT_MOUSE_BUTTON_FORWARD = (1U << 4),
    PADDLEBOAT_MOUSE_BUTTON_6 = (1U << 5),
    PADDLEBOAT_MOUSE_BUTTON_7 = (1U << 6),
    PADDLEBOAT_MOUSE_BUTTON_8 = (1U << 7)
};

מכשירי עכבר פיזיים לעומת מכשירי עכבר וירטואליים

הערך Paddleboat_MouseStatus מתוך PADDLEBOAT_MOUSE_CONTROLLER_EMULATED מציין שאין מכשיר עכבר פיזי, וספריית Game Controller מדמה עכבר וירטואלי באמצעות שלט מחובר. האינדקס הנמוך ביותר של בקר מחובר עם הדגל PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE מוגדר כעכבר וירטואלי. מובטח שמכשירי עכבר וירטואליים ידווחו רק על קואורדינטות של mouseX ו-mouseY. יכול להיות שמכשירי עכבר וירטואליים ידווחו על לחיצות מכפתור עכבר יחיד (שמאלי), אבל זה לא מובטח.