Thêm tính năng hỗ trợ thiết bị chuột

Sử dụng các hàm sau để thêm tính năng hỗ trợ thiết bị chuột vào trò chơi bằng cách sử dụng thư viện Tay điều khiển trò chơi. Chúng tôi sử dụng thuật ngữ thiết bị chuột để mô tả các loại chuột truyền thống, cũng như bàn di chuột hoặc bi xoay.

Thêm lệnh gọi lại trạng thái chuột

Thư viện Tay điều khiển trò chơi sử dụng lệnh gọi lại trạng thái chuột để thông báo cho trò chơi khi chuột được kết nối hoặc bị ngắt kết nối. Tính năng này chỉ hỗ trợ mỗi lần một lệnh gọi lại trạng thái chuột.

  • Để đăng ký lệnh gọi lại trạng thái chuột hoặc thay thế bất kỳ lệnh gọi lại nào đã đăng ký trước đó bằng hàm callback mới, hãy gọi hàm Paddleboat_setMouseStatusCallback.
  • Để loại bỏ bất kỳ lệnh gọi lại nào hiện đã được đăng ký, hãy truyền NULL hoặc nullptr trong thông số statusCallback.
  • Thông số userData là con trỏ tuỳ chọn trỏ đến dữ liệu do người dùng xác định. Thông số userData sẽ được truyền đến hàm callback. Con trỏ này được duy trì nội bộ cho đến khi được một lệnh gọi khác thay đổi thành Paddleboat_setMouseStatusCallback.
void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
  statusCallback, void *userData)

Chữ ký của hàm callback trạng thái chuột là:

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

Thông số enum mouseStatus có thể có ba giá trị:

  • PADDLEBOAT_MOUSE_NONE: Hiện không có thiết bị chuột nào được kết nối.
  • PADDLEBOAT_MOUSE_CONTROLLER_EMULATED: Một tay điều khiển đã kết nối đang mô phỏng chuột.
  • PADDLEBOAT_MOUSE_PHYSICAL: Một hoặc nhiều thiết bị chuột thực được kết nối. (Các thiết bị này bao gồm chuột, bàn di chuột, bi xoay hoặc các thiết bị tương tự khác).

Thông số userData chứa con trỏ userData được chỉ định trong lệnh gọi Paddleboat_setMouseStatusCallback gần đây nhất. userData có thể là NULL (RỖNG) hoặc nullptr.

Không phải tay điều khiển nào cũng mô phỏng chuột. Các tay điều khiển có thể mô phỏng chuột bằng cách sử dụng một trong các gậy điều khiển analog hoặc bàn di chuột tích hợp.

Thư viện Tay điều khiển trò chơi chỉ báo cáo dữ liệu từ một thiết bị chuột duy nhất. Các thiết bị chuột thực được ưu tiên hơn các thiết bị chuột ảo của tay điều khiển. Nếu được kết nối, chuột thực sẽ thế chỗ bất kỳ chuột ảo của tay điều khiển nào đang hoạt động trước đó.

Đọc dữ liệu về chuột

Gọi hàm Paddleboat_getMouseStatus để biết trạng thái của thiết bị chuột.

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

Dùng hàm Paddleboat_getMouseData để lấy dữ liệu về chuột hiện tại. Hàm này trả về PADDLEBOAT_NO_ERROR nếu đọc dữ liệu thành công, nếu không thì sẽ trả về một mã lỗi thích hợp.

bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

Cấu trúc Paddleboat_Mouse_Data chứa thông tin về:

  • Dấu thời gian sự kiện nhập bằng chuột gần đây nhất
  • Vị trí con trỏ hiện tại
  • Trạng thái của nút chuột
  • Trạng thái của con lăn chuột
struct Paddleboat_Mouse_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    int32_t mouseScrollDeltaH;
    int32_t mouseScrollDeltaV;
    float mouseX;
    float mouseY;
}
Thành phần cấu trúc Mô tả
timestamp Dấu thời gian của sự kiện nhập bằng chuột gần đây nhất. Giá trị dấu thời gian tính bằng micrô giây kể từ thời gian bắt đầu của đồng hồ.
buttonsDown Trường bit, mỗi bit bắt đầu từ bit 0 cho biết trạng thái ấn nút nếu được đặt.
mouseX
mouseY
Vị trí của chuột trong toạ độ pixel. Toạ độ vị trí có phạm vi từ 0.0 đến chiều rộng và chiều cao của màn hình.
mouseScrollDeltaH
mouseScrollDeltaV
Số sự kiện con lăn chuột tích lũy: kể từ lệnh gọi trước đó đến Paddleboat_getMouseData. Các giá trị này không chắc chắn chính xác, chỉ để cho biết hoạt động của con lăn chuột theo một hướng cụ thể. Hầu hết chuột đều có một con lăn được báo cáo trong mouseScrollDeltaV. Nếu chuột có con lăn bên hông, thì con lăn đó sẽ được báo cáo trong mouseScrollDeltaH. Các giá trị này được đặt lại thành 0 trong nội bộ sau lệnh gọi Paddleboat_getMouseData.

Thư viện Tay điều khiển trò chơi xác định hằng số mặt nạ bit cho các nút chuột trong tệp tiêu đề giao diện 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)
};

Thiết bị chuột thực và ảo

Paddleboat_MouseStatus của PADDLEBOAT_MOUSE_CONTROLLER_EMULATED cho biết rằng không có thiết bị chuột thực và thư viện Tay điều khiển trò chơi đang mô phỏng chuột ảo bằng tay điều khiển được kết nối. Chỉ mục tay điều khiển được kết nối thấp nhất có gắn cờ PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE được dùng làm chuột ảo. Các thiết bị chuột ảo chắc chắn sẽ báo cáo các toạ độ mouseXmouseY. Ngoài ra, các thiết bị này đôi khi có thể báo cáo số lần nhấn từ một nút chuột duy nhất (bên trái).