إضافة عمليات ربط أجهزة مخصّصة لوحدة التحكّم

تحتفظ مكتبة Game Controller بقاعدة بيانات داخلية لأجهزة التحكّم، تُستخدَم في ضبط الأزرار وتصميم محور الحركة وعمليات الربط لأجهزة التحكّم المعروفة وعملية ربط تلقائية لأجهزة التحكّم غير المعروفة. تتضمّن قاعدة البيانات العديد من أدوات التحكّم الشائعة، ولكنها قد لا تتضمّن جميع الأجهزة ذات الصلة بلعبة معيّنة. تتيح مكتبة Game Controller إمكانية التخصيص باستخدام دوال يمكنها تنفيذ ما يلي:

• استرداد قاعدة بيانات الربط الحالية
• إضافة إدخالات إلى قاعدة البيانات الحالية
• استبدال إدخالات قاعدة البيانات الحالية
• استبدال قاعدة البيانات الحالية بأكملها بقاعدة بيانات جديدة

تحديد جهاز

يتم تحديد أجهزة التحكّم من خلال قيمتَي productId وvendorId. يحتوي كل جهاز تحكّم تم التعرّف عليه على إدخال واحد على الأقل في قاعدة البيانات يتضمّن productId وvendorId متطابقَين. يتضمّن هيكل ربط أزرار وحدة التحكّم حقولاً تحدّد الحد الأدنى والأقصى لنطاق واجهة برمجة التطبيقات المؤهّلة في Android للإدخال. قد تتوفّر إدخالات متعدّدة تتضمّن القيمتين productId وvendorId نفسيهما في قاعدة البيانات طالما أنّها تتضمّن نطاقات فريدة للحدّ الأدنى والأقصى في واجهة برمجة التطبيقات.

قراءة بيانات إعادة الربط الحالية

استخدِم الدالة Paddleboat_getControllerRemapTableData لاسترداد بيانات إعادة الربط الحالية.

int32_t Paddleboat_getControllerRemapTableData(
   const int32_t destRemapTableEntryCount,
   Paddleboat_Controller_Mapping_Data* mappingData)

تعرض Paddleboat_getControllerRemapTableData إجمالي عدد إدخالات إعادة التعيين المتوفّرة في قاعدة البيانات الداخلية.

المَعلمة	الوصف
destRemapTableEntryCount	حجم مصفوفة عناصر Paddleboat_Controller_Mapping_Data التي تم تمريرها في المَعلمة mappingData.
mappingData	مؤشر إلى مصفوفة من عناصر Paddleboat_Controller_Mapping_Data

إذا كان destRemapTableEntryCount أصغر من إجمالي عدد إدخالات إعادة التعيين، سيتم نسخ عدد الإدخالات المحدّد بواسطة destRemapTableEntryCount فقط إلى mappingData.

إضافة بيانات إعادة الربط أو استبدالها

استخدِم الدالة Paddleboat_addControllerRemapData لإضافة إدخالات إعادة الربط أو استبدال قاعدة بيانات إعادة الربط الحالية.

void Paddleboat_addControllerRemapData(
   const Paddleboat_Remap_Addition_Mode addMode,
   const int32_t remapTableEntryCount,
   const Paddleboat_Controller_Mapping_Data* mappingData)

المَعلمة	الوصف
addMode	قواعد الإضافة المستخدَمة في العملية القيم الصالحة هي PADDLEBOAT_REMAP_ADD_MODE_DEFAULT أو PADDLEBOAT_REMAP_ADD_MODE_REPLACE_ALL
remapTableEntryCount	حجم مصفوفة عناصر Paddleboat_Controller_Mapping_Data التي تم تمريرها في المَعلمة mappingData.
mappingData	مؤشر إلى مصفوفة من عناصر Paddleboat_Controller_Mapping_Data

أوضاع الإضافة

إذا تم تحديد PADDLEBOAT_REMAP_ADD_MODE_REPLACE_ALL في addMode، سيتم حذف قاعدة البيانات الحالية واستبدالها بمحتويات المصفوفة الجديدة.

إذا تم تحديد PADDLEBOAT_REMAP_ADD_MODE_DEFAULT في addMode، سيتم تطبيق المعايير التالية على كل عنصر في المصفوفة التي تم تمريرها في mappingData:

• إذا كان Paddleboat_getControllerRemapTableData فريدًا (بمعنى آخر، إذا لم يكن vendorId وproductId متوفّرَين من قبل، أو كانا متوفّرَين ولكن بنطاق minApi أو maxApi غير متداخل)، تتم إضافة الإدخال إلى قاعدة البيانات الداخلية.
• إذا لم يكن Paddleboat_getControllerRemapTableData فريدًا (vendorId وproductId متوفّران وهناك تداخل في minApi أو maxApi)، سيتم استبدال الإدخال الحالي في قاعدة البيانات الداخلية.

تكون بنية Paddleboat_Controller_Mapping_Data على النحو التالي:

typedef struct Paddleboat_Controller_Mapping_Data {
    int16_t minimumEffectiveApiLevel; /** Min. API level for this entry */
    int16_t maximumEffectiveApiLevel; /** Max. API level, 0 = no max */
    int32_t vendorId; /** VendorID of the controller device for this entry */
    int32_t productId; /** ProductID of the controller device for this entry */
    int32_t flags; /** Flag bits, will be ORed with
                     * Paddleboat_Controller_Info.controllerFlags */

    /** AMOTION_EVENT_AXIS value for the corresponding Paddleboat control axis,
     *  or PADDLEBOAT_AXIS_IGNORED if unsupported. */
    uint16_t axisMapping[PADDLEBOAT_MAPPING_AXIS_COUNT];
    /** Button to set on positive or negative axis value,
     *  PADDLEBOAT_AXIS_BUTTON_IGNORED if none. */
    uint8_t axisPositiveButtonMapping[PADDLEBOAT_MAPPING_AXIS_COUNT];
    uint8_t axisNegativeButtonMapping[PADDLEBOAT_MAPPING_AXIS_COUNT];
    /** AKEYCODE_ value corresponding with the corresponding Paddleboat button.
     *  PADDLEBOAT_BUTTON_IGNORED if unsupported. */
    uint16_t buttonMapping[PADDLEBOAT_BUTTON_COUNT];
} Paddleboat_Controller_Mapping_Data;

مثال على عملية الربط

يوضّح ما يلي Paddleboat_Controller_Mapping_Data تم ملؤه لوصف وحدة تحكّم Google Stadia:

#define PADDLEBOAT_AXIS_BUTTON_DPAD_UP 0
#define PADDLEBOAT_AXIS_BUTTON_DPAD_LEFT 1
#define PADDLEBOAT_AXIS_BUTTON_DPAD_DOWN 2
#define PADDLEBOAT_AXIS_BUTTON_DPAD_RIGHT 3
#define PADDLEBOAT_AXIS_BUTTON_L2 9
#define PADDLEBOAT_AXIS_BUTTON_R2 12

static const Paddleboat_Controller_Mapping_Data stadia_controller_map[] = {
    16, 0, 0x18d1, 0x9400, PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD,
    {
        /* LX */ AMOTION_EVENT_AXIS_X,
        /* LY */ AMOTION_EVENT_AXIS_Y,
        /* RX */ AMOTION_EVENT_AXIS_Z,
        /* RY */ AMOTION_EVENT_AXIS_RZ,
        /* L1 */ PADDLEBOAT_AXIS_IGNORED,
        /* L2 */ AMOTION_EVENT_AXIS_BRAKE,
        /* R1 */ PADDLEBOAT_AXIS_IGNORED,
        /* R2 */ AMOTION_EVENT_AXIS_GAS,
        /* HX */ AMOTION_EVENT_AXIS_HAT_X,
        /* HY */ AMOTION_EVENT_AXIS_HAT_Y,
    },
    {
        /* LX */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* LY */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* RX */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* RY */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* L1 */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* L2 */ PADDLEBOAT_AXIS_BUTTON_L2,
        /* R1 */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* R2 */ PADDLEBOAT_AXIS_BUTTON_R2,
        /* HX */ PADDLEBOAT_AXIS_BUTTON_DPAD_RIGHT,
        /* HY */ PADDLEBOAT_AXIS_BUTTON_DPAD_DOWN,
    },
    {
        /* LX */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* LY */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* RX */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* RY */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* L1 */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* L2 */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* R1 */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* R2 */ PADDLEBOAT_AXIS_BUTTON_IGNORED,
        /* HX */ PADDLEBOAT_AXIS_BUTTON_DPAD_LEFT,
        /* HY */ PADDLEBOAT_AXIS_BUTTON_DPAD_UP,
    },
    {
        /* UP     */ AKEYCODE_DPAD_UP,
        /* LEFT   */ AKEYCODE_DPAD_LEFT,
        /* DOWN   */ AKEYCODE_DPAD_DOWN,
        /* RIGHT  */ AKEYCODE_DPAD_RIGHT,
        /* A      */ AKEYCODE_BUTTON_A,
        /* B      */ AKEYCODE_BUTTON_B,
        /* X      */ AKEYCODE_BUTTON_X,
        /* Y      */ AKEYCODE_BUTTON_Y,
        /* L1     */ AKEYCODE_BUTTON_L1,
        /* L2     */ AKEYCODE_BUTTON_L2,
        /* L3     */ AKEYCODE_BUTTON_THUMBL,
        /* R1     */ AKEYCODE_BUTTON_R1,
        /* R2     */ AKEYCODE_BUTTON_R2,
        /* R3     */ AKEYCODE_BUTTON_THUMBR,
        /* SELECT */ AKEYCODE_BUTTON_SELECT,
        /* START  */ AKEYCODE_BUTTON_START,
        /* SYSTEM */ AKEYCODE_BUTTON_MODE,
        /* TOUCHP */ PADDLEBOAT_BUTTON_IGNORED,
        /* AUX1   */ PADDLEBOAT_BUTTON_IGNORED,
        /* AUX2   */ PADDLEBOAT_BUTTON_IGNORED,
        /* AUX3   */ PADDLEBOAT_BUTTON_IGNORED,
        /* AUX4   */ PADDLEBOAT_BUTTON_IGNORED
    }
};