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

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

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

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

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