Unterstützung für Mausgeräte hinzufügen

Mit den folgenden Funktionen können Sie Ihrem Spiel Unterstützung für Mausgeräte hinzufügen, indem Sie die Game Controller-Bibliothek verwenden. Wir verwenden den Begriff „Mausgeräte“ hier, um sowohl herkömmliche Mäuse als auch Touchpads oder Trackballs zu beschreiben.

Mausstatus-Callback hinzufügen

Die Game Controller-Bibliothek verwendet einen Mausstatus-Callback, um ein Spiel zu benachrichtigen, wenn eine Maus angeschlossen oder getrennt wird. Es wird jeweils nur ein Rückruf für den Mausstatus unterstützt.

  • Wenn Sie einen Mausstatus-Callback registrieren oder einen zuvor registrierten Callback durch eine neue Callback-Funktion ersetzen möchten, rufen Sie die Funktion Paddleboat_setMouseStatusCallback auf.
  • Wenn Sie einen aktuell registrierten Callback entfernen möchten, übergeben Sie NULL oder nullptr im Parameter statusCallback.
  • Der Parameter userData ist ein optionaler Zeiger auf benutzerdefinierte Daten. Der Parameter userData wird an die Callback-Funktion übergeben. Dieser Zeiger wird intern beibehalten, bis er durch einen anderen Aufruf von Paddleboat_setMouseStatusCallback geändert wird.
void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
  statusCallback, void *userData)

Die Funktionssignatur der Mausstatus-Callback-Funktion lautet:

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

Der Enum-Parameter mouseStatus hat drei mögliche Werte:

  • PADDLEBOAT_MOUSE_NONE: Derzeit ist keine Maus angeschlossen.
  • PADDLEBOAT_MOUSE_CONTROLLER_EMULATED: Ein verbundener Controller simuliert eine Maus.
  • PADDLEBOAT_MOUSE_PHYSICAL: Es sind eine oder mehrere physische Mäuse angeschlossen. Dazu gehören Mäuse, Touchpads, Trackballs und ähnliche Geräte.

Der Parameter userData enthält den userData-Zeiger, der im letzten Aufruf von Paddleboat_setMouseStatusCallback angegeben wurde. userData kann NULL oder nullptr sein.

Nicht alle Controller simulieren eine Maus. Controller können eine Maus mit einem der Analogsticks oder mit einem integrierten Touchpad simulieren.

Die Game Controller-Bibliothek meldet nur Daten von einem einzelnen Mausgerät. Physische Mäuse haben Vorrang vor virtuellen Controllermäusen. Wenn eine physische Maus angeschlossen ist, übernimmt sie die Steuerung von einer zuvor aktiven virtuellen Controller-Maus.

Mausdaten lesen

Rufen Sie die Funktion Paddleboat_getMouseStatus auf, um den Status des Mausgeräts abzurufen.

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

Mit der Funktion Paddleboat_getMouseData können Sie die aktuellen Mausdaten abrufen. Diese Funktion gibt PADDLEBOAT_NO_ERROR zurück, wenn Daten erfolgreich gelesen wurden. Andernfalls wird ein entsprechender Fehlercode zurückgegeben.

bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

Die Paddleboat_Mouse_Data-Struktur enthält Informationen zu:

  • Zeitstempel des letzten Maus-Eingabeereignisses
  • Die aktuelle Zeigerposition
  • Status der Maustasten
  • Status von Mausrädern
struct Paddleboat_Mouse_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    int32_t mouseScrollDeltaH;
    int32_t mouseScrollDeltaV;
    float mouseX;
    float mouseY;
}
Gebäudemitglied Beschreibung
timestamp Zeitstempel des letzten Maus-Eingabeereignisses. Der Zeitstempelwert wird in Mikrosekunden seit der Takt-Epoche angegeben.
buttonsDown Bitfeld. Jedes Bit ab Bit 0 gibt an, ob eine Taste gedrückt ist, wenn es gesetzt ist.
mouseX
mouseY 		Mausposition in Pixelkoordinaten. Die Koordinaten für die Position haben einen Bereich von 0.0 bis zur Bildschirmbreite und ‑höhe.
mouseScrollDeltaH
mouseScrollDeltaV 		Die Anzahl der kumulativen Mausrad-Ereignisse seit dem letzten Aufruf von Paddleboat_getMouseData. Diese Werte sind nicht garantiert genau, sondern geben nur einen Hinweis auf die Scrollradaktivität in einer bestimmten Richtung. Die meisten Mäuse haben ein Scrollrad, das in mouseScrollDeltaV gemeldet wird. Wenn eine Maus ein seitliches Scrollrad hat, wird dies in mouseScrollDeltaH angegeben. Diese Werte werden nach einem Aufruf von Paddleboat_getMouseData intern auf 0 zurückgesetzt.

In der Headerdatei für die paddleboat.h-Schnittstelle sind Bitmaskenkonstanten für Maustasten definiert:

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)
};

Physische und virtuelle Mausgeräte

Ein Paddleboat_MouseStatus von PADDLEBOAT_MOUSE_CONTROLLER_EMULATED gibt an, dass kein physisches Mausgerät vorhanden ist und die Game Controller-Bibliothek eine virtuelle Maus mit einem verbundenen Controller simuliert. Der niedrigste verbundene Controllerindex mit dem Flag PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE wird als virtuelle Maus verwendet. Bei virtuellen Mäusen werden garantiert nur mouseX- und mouseY-Koordinaten gemeldet. Virtuelle Mäuse melden möglicherweise Drückvorgänge von einer einzelnen (linken) Maustaste, dies ist jedoch nicht garantiert.