Thêm các bản đồ ánh xạ thiết bị điều khiển tuỳ chỉnh

Thư viện Tay điều khiển trò chơi duy trì một cơ sở dữ liệu nội bộ gồm các thiết bị điều khiển, dùng để định cấu hình các nút, bố cục trục chuyển động, một bản đồ ánh xạ cho các tay điều khiển đã nhận dạng và một bản đồ ánh xạ mặc định cho các tay điều khiển chưa nhận dạng. Cơ sở dữ liệu này bao gồm nhiều tay điều khiển phổ biến, nhưng có thể không bao gồm tất cả thiết bị liên quan đến một trò chơi cụ thể. Thư viện Tay điều khiển trò chơi hỗ trợ tính năng tuỳ chỉnh bằng các hàm có thể:

• Truy xuất cơ sở dữ liệu bản đồ ánh xạ hiện có.
• Thêm mục nhập vào cơ sở dữ liệu hiện có.
• Thay thế các mục nhập cơ sở dữ liệu hiện có.
• Thay thế toàn bộ cơ sở dữ liệu hiện có bằng một cơ sở dữ liệu mới.

Xác định thiết bị

Các thiết bị điều khiển được xác định bằng các giá trị productId và vendorId. Mỗi thiết bị điều khiển được nhận dạng có ít nhất một mục nhập trong cơ sở dữ liệu có productId và vendorId khớp. Cấu trúc ánh xạ tay điều khiển bao gồm các trường chỉ định phạm vi API Android tối thiểu và tối đa cho mục nhập. Nhiều mục nhập có cùng productId và vendorId có thể tồn tại trong cơ sở dữ liệu, miễn là các mục đó có phạm vi API tối thiểu và tối đa duy nhất.

Đọc dữ liệu ánh xạ lại hiện có

Sử dụng hàm Paddleboat_getControllerRemapTableData để truy xuất dữ liệu ánh xạ lại hiện có.

int32_t Paddleboat_getControllerRemapTableData(
   const int32_t destRemapTableEntryCount,
   Paddleboat_Controller_Mapping_Data* mappingData)

Paddleboat_getControllerRemapTableData trả về tổng số mục nhập ánh xạ lại có trong cơ sở dữ liệu nội bộ.

Thông số	Mô tả
destRemapTableEntryCount	Kích thước mảng của các thành phần Paddleboat_Controller_Mapping_Data được truyền trong thông số mappingData.
mappingData	Con trỏ trỏ đến một mảng thành phần Paddleboat_Controller_Mapping_Data.

Nếu destRemapTableEntryCount nhỏ hơn tổng số mục nhập ánh xạ lại, thì chỉ có số mục nhập do destRemapTableEntryCount chỉ định được sao chép vào mappingData.

Thêm hoặc thay thế dữ liệu ánh xạ lại

Sử dụng hàm Paddleboat_addControllerRemapData để thêm mục nhập ánh xạ lại hoặc thay thế cơ sở dữ liệu ánh xạ lại hiện có.

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

Thông số	Mô tả
addMode	Các quy tắc bổ sung dùng cho thao tác. Các giá trị hợp lệ là PADDLEBOAT_REMAP_ADD_MODE_DEFAULT hoặc PADDLEBOAT_REMAP_ADD_MODE_REPLACE_ALL
remapTableEntryCount	Kích thước mảng của các thành phần Paddleboat_Controller_Mapping_Data được truyền trong thông số mappingData.
mappingData	Con trỏ trỏ đến một mảng thành phần Paddleboat_Controller_Mapping_Data.

Các chế độ bổ sung

Nếu PADDLEBOAT_REMAP_ADD_MODE_REPLACE_ALL được chỉ định trong addMode, cơ sở dữ liệu hiện có sẽ bị xoá và thay thế bằng nội dung của mảng mới.

Nếu PADDLEBOAT_REMAP_ADD_MODE_DEFAULT được chỉ định trong addMode, các tiêu chí sau sẽ được áp dụng cho từng thành phần trong mảng được truyền trong mappingData:

• Nếu Paddleboat_getControllerRemapTableData là duy nhất (nói cách khác, vendorId vàproductId chưa tồn tại hoặc đã tồn tại nhưng có phạm vi minApi hoặc maxApi không chồng chéo), mục nhập sẽ được thêm vào cơ sở dữ liệu nội bộ.
• Nếu Paddleboat_getControllerRemapTableData không phải là duy nhất (vendorId và productId tồn tại và minApi hoặc maxApi chồng chéo), mục nhập hiện có trong cơ sở dữ liệu nội bộ sẽ bị thay thế.

Cấu trúc Paddleboat_Controller_Mapping_Data là:

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;

Ví dụ về ánh xạ

Phần sau minh hoạ Paddleboat_Controller_Mapping_Data được điền để mô tả tay điều khiển 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
    }
};