添加鼠标设备支持

您可以利用 Game Controller 库,通过以下函数为您的游戏添加鼠标设备支持。在本文中,我们使用“鼠标设备”一词来描述传统鼠标以及触控板或轨迹球。

添加鼠标状态回调

Game Controller 库使用鼠标状态回调在鼠标连接或断开连接时通知游戏。它一次仅支持一个鼠标状态回调。

  • 如需注册鼠标状态回调或将任何之前注册的回调替换为新的回调函数,请调用 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

并非所有控制器都会模拟鼠标。控制器可以使用一个模拟摇杆来模拟鼠标,也可以使用集成式触控板模拟鼠标。

Game Controller 库仅报告来自单个鼠标设备的数据。实体鼠标设备的优先级高于虚拟控制器鼠标设备。如果连接了实体鼠标,它会接替之前任何已启用的虚拟控制器鼠标。

读取鼠标数据

通过调用 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 最近的鼠标输入事件的时间戳。时间戳值是自纪元以来的微秒数。
buttonsDown 位字段,从 0 位开始的每个位都表示一个按钮按下状态(若已设置)。
mouseX
mouseY
鼠标在像素坐标上的位置。位置坐标的范围是 0.0 到屏幕宽度和高度。
mouseScrollDeltaH
mouseScrollDeltaV
累计鼠标滚轮事件计数:自上次调用 Paddleboat_getMouseData 开始计算。这些值不一定非常精确,只能指示滚轮在特定方向上的活动情况。大多数鼠标都有一个滚轮(在 mouseScrollDeltaV 中报告)。如果鼠标有侧滚轮,会在 mouseScrollDeltaH 中报告。在调用 Paddleboat_getMouseData 后,这些值会在内部重置为 0

Game Controller 库在 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_MouseStatusPADDLEBOAT_MOUSE_CONTROLLER_EMULATED,则表示不存在实体鼠标设备,并且 Game Controller 库正使用已连接的控制器模拟虚拟鼠标。设置了 PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE 标志且索引最小的已连接控制器将用作虚拟鼠标。虚拟鼠标设备只能保证报告 mouseXmouseY 坐标;还有可能报告单个(左)鼠标按钮是否被按下,但这一点不能保证。