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

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

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

تحديد جهاز

يتم تحديد أجهزة وحدات التحكّم من خلال قيمتَي 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
    }
};