新增滑鼠裝置支援

您可以使用下列函式，透過遊戲控制器程式庫將滑鼠裝置支援加入遊戲。這裡使用「滑鼠」這個詞彙來描述傳統滑鼠、觸控板或軌跡球。

新增滑鼠狀態回呼

當使用者連線到滑鼠或中斷連線時，遊戲控制器程式庫會使用滑鼠狀態回呼來通知遊戲。一次僅支援一個滑鼠狀態回呼。

• 如要註冊滑鼠狀態回呼，或以新的回呼函式取代任何先前註冊的回呼，請呼叫 Paddleboat_setMouseStatusCallback 函式。
• 如要移除目前已註冊的回呼，請在 statusCallback 參數中傳遞 NULL 或 nullptr。
• userData 參數是使用者定義資料的選用指標。userData 參數會傳遞到回呼函式。此指標會在內部保留，直到再次呼叫 Paddleboat_setMouseStatusCallback 進行變更。

void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
  statusCallback, void *userData)

滑鼠狀態回呼函式的函式簽名如下：

typedef void (*Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus
  mouseStatus, void *userData)

mouseStatus 列舉參數共有三個值：

• PADDLEBOAT_MOUSE_NONE：目前未連結任何滑鼠裝置。
• PADDLEBOAT_MOUSE_CONTROLLER_EMULATED：已連結的控制器正在模擬滑鼠。
• PADDLEBOAT_MOUSE_PHYSICAL：連接一或多個實體滑鼠裝置。(這類裝置包括滑鼠、觸控板、軌跡球或其他類似裝置)。

userData 參數包含上次呼叫 Paddleboat_setMouseStatusCallback 時指定的 userData 指標。userData 可以是 NULL 或 nullptr。

並非所有控制器都會模擬滑鼠。控制器可以使用其中一個類比搖桿或整合式觸控板來模擬滑鼠。

遊戲控制器程式庫只會回報單一滑鼠滑鼠裝置的資料。實體滑鼠裝置的優先順序比虛擬控制器滑鼠裝置優先。如果連結了實際滑鼠，就會從先前使用過的虛擬控制器接管滑鼠。

讀取滑鼠資料

呼叫 Paddleboat_getMouseStatus 函式以取得滑鼠裝置的狀態。

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

使用 Paddleboat_getMouseData 函式取得目前的滑鼠資料。如果能順利讀取資料，這個函式會傳回 PADDLEBOAT_NO_ERROR，否則會傳回適當的錯誤代碼。

bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

Paddleboat_Mouse_Data 結構包含下列項目的相關資訊：

• 最新的滑鼠輸入事件時間戳記
• 目前遊標位置
• 滑鼠按鈕狀態
• 滑鼠滾輪狀態

struct Paddleboat_Mouse_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    int32_t mouseScrollDeltaH;
    int32_t mouseScrollDeltaV;
    float mouseX;
    float mouseY;
}

遊戲控制器程式庫定義了 paddleboat.h 介面標頭檔案中的滑鼠按鈕位元遮罩常數：

enum Paddleboat_Mouse_Buttons {
    PADDLEBOAT_MOUSE_BUTTON_LEFT = (1U << 0),
    PADDLEBOAT_MOUSE_BUTTON_RIGHT = (1U << 1),
    PADDLEBOAT_MOUSE_BUTTON_MIDDLE = (1U << 2),
    PADDLEBOAT_MOUSE_BUTTON_BACK = (1U << 3),
    PADDLEBOAT_MOUSE_BUTTON_FORWARD = (1U << 4),
    PADDLEBOAT_MOUSE_BUTTON_6 = (1U << 5),
    PADDLEBOAT_MOUSE_BUTTON_7 = (1U << 6),
    PADDLEBOAT_MOUSE_BUTTON_8 = (1U << 7)
};

實體滑鼠裝置與虛擬滑鼠裝置

PADDLEBOAT_MOUSE_CONTROLLER_EMULATED 的 Paddleboat_MouseStatus 表示沒有實體滑鼠裝置，且遊戲控制器程式庫會使用已連結的控制器模擬虛擬滑鼠。具有 PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE 旗標集的最低連結控制器索引會用作虛擬滑鼠。虛擬滑鼠裝置只能回報 mouseX 和 mouseY 座標。虛擬滑鼠裝置可回報單個 (左) 滑鼠按鈕的點擊次數，但無法保證結果。