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

Mit den folgenden Funktionen können Sie Ihrem Spiel mithilfe der Controller-Bibliothek Mausgeräte hinzufügen. Der Begriff „Mausgeräte“ bezieht sich hier sowohl auf herkömmliche Mäuse als auch für Touchpads oder Trackballs.

Mausstatus-Callback hinzufügen

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

• Wenn Sie einen Mausstatus-Callback registrieren oder einen zuvor registrierten Callback durch eine neue Callback-Funktion ersetzen möchten, rufen Sie die Paddleboat_setMouseStatusCallback-Funktion auf.
• Wenn Sie einen derzeit 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 Callback-Funktion für den Mausstatus lautet:

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

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

• PADDLEBOAT_MOUSE_NONE: Es ist derzeit kein Mausgerät verbunden.
• PADDLEBOAT_MOUSE_CONTROLLER_EMULATED: Ein verbundener Controller simuliert eine Maus.
• PADDLEBOAT_MOUSE_PHYSICAL: Mindestens ein physisches Mausgerät ist verbunden. Dazu gehören eine Maus, ein Touchpad, ein Trackball oder andere ä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 Mausgeräte haben Priorität vor Mausgeräten mit virtuellem Controller. Wenn eine physische Maus angeschlossen ist, übernimmt sie alle zuvor aktiven Maus des virtuellen Controllers.

Mausdaten lesen

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

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 Mauseingabeereignisses
• Die aktuelle Zeigerposition
• Status der Maustasten
• Status der Mausräder

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 Mauseingabeereignisses. Der Zeitstempelwert wird in Mikrosekunden seit der Uhrzeit angegeben.
buttonsDown	Bitfeld. Jedes Bit ab Bit 0 bedeutet, dass die Schaltfläche abgesetzt ist, sofern festgelegt.
mouseX mouseY	Mausposition in Pixelkoordinaten. Positionskoordinaten haben einen Bereich von 0.0 bis zur Bildschirmbreite und -höhe.
mouseScrollDeltaH mouseScrollDeltaV	Anzahl der kumulativen Scrollradereignisse der Maus: seit dem vorherigen Aufruf von Paddleboat_getMouseData. Diese Werte sind nicht zwangsläufig präzise. Sie geben lediglich einen Hinweis auf die Scrollradaktivität in einer bestimmten Richtung. Die meisten Mäuse haben nur ein Scrollrad. Dies wird in mouseScrollDeltaV angegeben. Wenn eine Maus ein seitliches Laufrad hat, wird dies in mouseScrollDeltaH gemeldet. Diese Werte werden nach einem Aufruf von Paddleboat_getMouseData intern auf 0 zurückgesetzt.

Die Game Controller-Bibliothek definiert Bitmaskenkonstanten für Maustasten in der paddleboat.h-Schnittstellenheaderdatei:

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 Mäuse im Vergleich

Ein Paddleboat_MouseStatus mit dem Wert PADDLEBOAT_MOUSE_CONTROLLER_EMULATED bedeutet, dass keine physische Maus vorhanden ist und die Game Controller-Bibliothek eine virtuelle Maus mithilfe eines verbundenen Controllers simuliert. Der niedrigste verbundene Controller-Index mit dem gesetzten Flag PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE wird als virtuelle Maus verwendet. Virtuelle Mausgeräte melden garantiert nur mouseX- und mouseY-Koordinaten. Virtuelle Mäuse können das Drücken einer einzigen (linken) Maustaste melden. Das ist jedoch nicht garantiert.