新增滑鼠裝置支援

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

新增滑鼠狀態回呼

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

  • 如要註冊滑鼠狀態回呼,或以新的回呼函式取代任何先前註冊的回呼,請呼叫 Paddleboat_setMouseStatusCallback 函式。
  • 如要移除目前已註冊的回呼,請在 statusCallback 參數中傳遞 NULLnullptr
  • 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;
}
結構成員 說明
timestamp 最近一次滑鼠輸入事件的時間戳記。時間戳記值是以微秒為單位,自時鐘 Epoch 時間起算。
buttonsDown 位元欄位 (從第 0 個位元開始的每位元) 即代表按鈕按下的狀態 (如有設定)。
mouseX
mouseY
滑鼠位置 (以像素為單位)。 位置座標的 0.0 範圍為螢幕寬度和高度。
mouseScrollDeltaH
mouseScrollDeltaV
滑鼠懸停滾動事件的計數:從上次呼叫 Paddleboat_getMouseData 至今。這些值並不保證精確,只能指出滾輪的特定方向活動。大部分的滑鼠都具有一個滾輪,以 mouseScrollDeltaV 方式回報。如果滑鼠有側邊滾輪,則會以 mouseScrollDeltaH 方式回報。呼叫 Paddleboat_getMouseData 後,這些值會在內部重設為 0

遊戲控制器程式庫定義了 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_EMULATEDPaddleboat_MouseStatus 表示沒有實體滑鼠裝置,且遊戲控制器程式庫會使用已連結的控制器模擬虛擬滑鼠。具有 PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE 旗標集的最低連結控制器索引會用作虛擬滑鼠。虛擬滑鼠裝置只能回報 mouseXmouseY 座標。虛擬滑鼠裝置可回報單個 (左) 滑鼠按鈕的點擊次數,但無法保證結果。