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

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

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

التعرّف على جهاز

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