Zum Hauptinhalt springen
Diese Seite wurde automatisch übersetzt und kann Fehler enthalten. Original auf Englisch ansehen

Referenzen

Die Klasse BhapticsKit stellt Funktionen zur Steuerung von bHaptics-Haptikgeräten aus Swift bereit. Sie ermöglicht es Ihnen, Haptikgeräte zu verbinden, haptische Pattern abzuspielen, Gerätemotoren direkt zu steuern und die Haptik-Wiedergabe zu verwalten.

import BhapticsPlugin

let kit = BhapticsKit()

Funktionen, die Haptik abspielen, geben eine Request-ID zurück. Mit ihr können Sie die Wiedergabe prüfen oder stoppen.

Lifecycle​

init​

init()
init(delegate: BhapticsKitDelegate?)

Erstellt die SDK-Instanz. Erstellen Sie eine einzige Instanz und behalten Sie sie während der gesamten Laufzeit Ihrer App bei.

Unter iOS und visionOS startet das Erstellen der Instanz Bluetooth, und das System fragt den Benutzer nach der Bluetooth-Berechtigung.

Parameter​

  • delegate(optional): Empfängt Änderungen des Bluetooth- und Gerätestatus. Siehe BhapticsKitDelegate.

initialize​

func initialize(appId: String, apiKey: String, defaultSetting: String) async -> Bool
func initialize(appId: String, apiKey: String, defaultSetting: String)

Initialisiert die Haptik-Umgebung. Diese Funktion sollte aufgerufen werden, bevor die ereignisbezogenen Funktionen verwendet werden.

  • Unter iOS und visionOS lädt sie die haptischen Ereignisse Ihrer haptischen App vom Server herunter.
  • Unter macOS stellt sie die Verbindung zum bHaptics Player her. Wenn der bHaptics Player installiert ist, aber nicht läuft, startet sie den bHaptics Player.

Die Nicht-async-Version führt dieselbe Initialisierung im Hintergrund aus und gibt kein Ergebnis zurück.

Parameter​

  • appId: Im bHaptics Developer Portal erstellte Anwendungs-ID.
  • apiKey: Im bHaptics Developer Portal erstellter API Key.
  • defaultSetting: Übergeben Sie einen leeren String ("").

Rückgabewert​

Erfolgsstatus der Initialisierung.

Beispiel​

let result = await kit.initialize(appId: "your_app_id", apiKey: "your_api_key", defaultSetting: "")
print("Initialization result: \(result)")

delegate​

var delegate: BhapticsKitDelegate?

Empfängt Änderungen des Bluetooth- und Gerätestatus. Siehe BhapticsKitDelegate.

Ereignisbasierte Haptik abspielen​

Spielen Sie haptische Pattern ab, die an bestimmte Ereignisse gebunden sind (entworfen im bHaptics Designer/Portal). Dies sind die empfohlenen Funktionen für die meisten Anwendungen.

play​

func play(eventId: String) -> Int

Spielt das vordefinierte haptische Ereignis ab.

Parameter​

  • eventId: Name des haptischen Ereignisses.

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

let requestId = kit.play(eventId: "heartbeat")
print("Playback request ID: \(requestId)")

playParam​

func playParam(
    eventId: String,
    requestId: Int? = nil,
    intensity: Float,
    duration: Float,
    angleX: Float,
    offsetY: Float
) -> Int

Spielt das haptische Ereignis ab und passt dabei die Stärke, die Duration und die Richtung der Haptik an.

Parameter​

  • eventId: Name des haptischen Ereignisses.
  • requestId(optional): Request-ID, die für diese Wiedergabe verwendet werden soll. Wenn sie weggelassen wird, wird eine zufällige ID vergeben.
  • intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
  • duration: Multiplikator für die Duration. (Standard: 1.0)
  • angleX: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
  • offsetY: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

let requestId = kit.playParam(eventId: "pistol_r", intensity: 1.0, duration: 1.0, angleX: 0.0, offsetY: 0.0)

playLoop​

func playLoop(
    eventId: String,
    intensity: Float,
    duration: Float,
    angleX: Float,
    offsetY: Float,
    interval: Int,
    maxCount: Int
) -> Int

Spielt haptische Ereignisse in einer Schleife ab.

Parameter​

  • eventId: Name des haptischen Ereignisses.
  • intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
  • duration: Multiplikator für die Duration. (Standard: 1.0)
  • angleX: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
  • offsetY: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)
  • interval: Zeitintervall zwischen den Schleifendurchläufen in Millisekunden.
  • maxCount: Anzahl der Schleifendurchläufe.

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

let requestId = kit.playLoop(eventId: "heartbeat", intensity: 0.8, duration: 1.0, angleX: 90, offsetY: 0, interval: 150, maxCount: 5)

playWithStartTime​

func playWithStartTime(
    eventId: String,
    startMillis: Int,
    intensity: Float,
    duration: Float,
    angleX: Float,
    offsetY: Float
) -> Int

Spielt das haptische Ereignis ab einem bestimmten Zeitpunkt ab. Verwenden Sie dies, um Haptik mit bereits laufenden Medien zu synchronisieren.

Parameter​

  • eventId: Name des haptischen Ereignisses.
  • startMillis: Startzeitpunkt der Wiedergabe, gemessen in Millisekunden ab dem Beginn des Ereignisses.
  • intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
  • duration: Multiplikator für die Duration. (Standard: 1.0)
  • angleX: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
  • offsetY: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

// Start from 1.5 seconds into the event.
let requestId = kit.playWithStartTime(eventId: "music_video", startMillis: 1500, intensity: 1.0, duration: 1.0, angleX: 0, offsetY: 0)

playWithoutResult​

func playWithoutResult(eventId: String, intensity: Float, duration: Float, angleX: Float, offsetY: Float)

Spielt haptische Ereignisse ab, ohne eine Request-ID zurückzugeben (fire-and-forget).

Parameter​

  • eventId: Name des haptischen Ereignisses.
  • intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
  • duration: Multiplikator für die Duration. (Standard: 1.0)
  • angleX: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
  • offsetY: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)

Beispiel​

kit.playWithoutResult(eventId: "heartbeat", intensity: 0.8, duration: 1.0, angleX: 90, offsetY: 0.25)

Haptik direkt abspielen​

Wenn Sie Haptik ohne Ereignisse abspielen möchten, verwenden Sie diese Funktionen.

position ist ein Int-Wert, der mit den anderen bHaptics SDKs geteilt wird. Verwenden Sie BhapticsPosition.index, um ihn zu erhalten. Siehe BhapticsPosition.

playDot​

@discardableResult
func playDot(position: Int, durationMillis: Int, arr: [Int]) -> Int

Spielt haptisches Feedback auf dem bestimmten haptischen Aktuator ab.

Parameter​

  • position: Typ des Haptikgeräts für die Wiedergabe. Weitere Informationen finden Sie hier.
    WertGerätAnzahl der Motoren
    0TactSuit Pro32
    1TactSleeve(Left)3
    2TactSleeve(Right)3
    3TactVisor4
    4Tactosy for Hands(Left)3
    5Tactosy for Hands(Right)3
    6Tactosy for Feet(Left)3
    7Tactosy for Feet(Right)3
    8TactGlove(Left)8
    9TactGlove(Right)8
  • durationMillis: Die Duration der Haptik, gemessen in Millisekunden. Ein Wert größer oder gleich 100 wird empfohlen.
  • arr: Legen Sie die Länge des Arrays entsprechend der Anzahl der Motoren des Geräts fest. Die Werte im Array geben die Intensity der Motoren an. Der gültige Bereich für jeden Wert im Array ist: [0 - 100]

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

// Sequentially activate 32 motors
let motorsCount = 32

for i in 0..<motorsCount {
    var motors = [Int](repeating: 0, count: motorsCount)
    motors[i] = 50
    kit.playDot(position: BhapticsPosition.Vest.index, durationMillis: 500, arr: motors)
    try await Task.sleep(nanoseconds: 500_000_000)
}

playPath​

@discardableResult
func playPath(position: Int, durationMillis: Int, x: [Float], y: [Float], intensity: [Int]) -> Int

Spielt Haptik rund um bestimmte Koordinaten ab. Anders als die Funktion playDot, die die haptische Intensity für jeden haptischen Aktuator einzeln angibt, gibt diese Methode die haptische Intensity für bestimmte Koordinaten an.

Bei der Angabe der haptischen Position bietet playDot eine diskrete Steuerung, während playPath kontinuierlicher ist. playDot weist einzelnen Aktuatoren eine Intensity zu, wohingegen playPath die Angabe einer Intensity für bestimmte Koordinaten (zwischen 0 und 1 sowohl für die X- als auch die Y-Achse) ermöglicht, wodurch die nahegelegenen Aktuatoren entsprechend vibrieren.

Sie können mehrere Koordinaten mit mehreren Intensities angeben. Beachten Sie, dass alle Aktuatoren um diese Koordinaten im Array gleichzeitig (zur selben Zeit) aktiviert werden, nicht nacheinander. Darüber hinaus muss die Größe aller Arrays gleich sein.

Indem Sie diese Funktion kontinuierlich aufrufen und dabei die Werte schrittweise ändern, können Sie den Effekt eines sich bewegenden haptischen Punktes erzielen.

Koordinate

Parameter​

  • position: Typ des Haptikgeräts für die Wiedergabe. Siehe die Tabelle unter playDot.
  • durationMillis: Die Duration der Haptik, gemessen in Millisekunden. Ein Wert größer oder gleich 100 wird empfohlen.
  • x: Array von X-Koordinaten für den haptischen Effect. Jeder Wert muss im Bereich liegen: [0.0 - 1.0]
  • y: Array von Y-Koordinaten für den haptischen Effect. Jeder Wert muss im Bereich liegen: [0.0 - 1.0]
  • intensity: Array von Intensity-Werten für jede Koordinate. Die Länge muss mit der Anzahl der Koordinaten übereinstimmen. Jeder Wert muss im Bereich liegen: [0 - 100]

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

// Path of point #1
let x1: [Float] = [0.738, 0.723, 0.709, 0.696, 0.682, 0.667, 0.653]
let y1: [Float] = [0.680, 0.715, 0.749, 0.782, 0.816, 0.852, 0.885]
// Path of point #2
let x2: [Float] = [0.061, 0.072, 0.102, 0.184, 0.254, 0.310, 0.363]
let y2: [Float] = [0.632, 0.587, 0.542, 0.498, 0.411, 0.366, 0.301]

for i in 0..<x1.count {
    // Point #1 and #2 will vibrate at the same time.
    kit.playPath(position: BhapticsPosition.Vest.index, durationMillis: 250, x: [x1[i], x2[i]], y: [y1[i], y2[i]], intensity: [20, 60])
    try await Task.sleep(nanoseconds: 250_000_000)
}

playGlove​

@discardableResult
func playGlove(position: Int, points: [GlovePoint], frequency: Int, repeatCount: Int) -> Int

Nur TactGlove. Spielt Haptik im TactGlove ab. Anders als bei der Verwendung von playDot können Sie die haptische Duration und die Änderungen der Vibrations-Intensity fein einstellen. Dies ermöglicht eine noch detailliertere Darstellung von haptischem Feedback.

Übergeben Sie einen GlovePoint für jeden Motor, den Sie ansteuern möchten. Mindestens ein Punkt ist erforderlich, damit es funktioniert.

struct GlovePoint {
    var index: Int
    var intensity: Int
    var shape: Int
    var playTime: Int

    init(index: Int, intensity: Int, shape: Int = 0, playTime: Int = 0)
}

Parameter​

  • position: Typ des Haptikgeräts für die Wiedergabe. Verwenden Sie nur 8 oder 9.

    WertGerät
    8TactGlove(Left)
    9TactGlove(Right)

  • points: Array von GlovePoint.

    • index: Index des Motors.

      IndexMotor befindet sich an …
      0Spitze des Daumens
      1Spitze des Zeigefingers
      2Spitze des Mittelfingers
      3Spitze des Ringfingers
      4Spitze des kleinen Fingers
      5Am Handgelenk
      6An der Handfläche (Daumenseite)
      7An der Handfläche (Seite des kleinen Fingers)

    • intensity: Intensity des Motors. Gültiger Bereich: [0 - 100]

    • playTime: Zeitintervall für die Ansteuerung.

      WertPlaytimes
      15ms
      210ms
      420ms
      630ms
      840ms

    • shape: Form der Änderung der haptischen Intensity im Laufe der Zeit.

      WertWaveform
      0Konstante Intensity für die Duration
      1Beginnt bei der angegebenen Intensity und nimmt um die Hälfte ab
      2Beginnt bei der Hälfte der angegebenen Intensity und steigt auf die angegebene an.

  • frequency: Vibrationsfrequenz des Handgelenkmotors in Hz. Gilt nur für TactGlove DK3. Übergeben Sie 0, um den Standardwert (80) zu verwenden.

  • repeatCount: Anzahl der Wiederholungen.

Rückgabewert​

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen.

Beispiel​

let points = (0..<8).map { GlovePoint(index: $0, intensity: 100, shape: 2, playTime: 8) }

// Left hand
kit.playGlove(position: BhapticsPosition.GloveL.index, points: points, frequency: 0, repeatCount: 1)

// Right hand
kit.playGlove(position: BhapticsPosition.GloveR.index, points: points, frequency: 0, repeatCount: 1)

Wiedergabesteuerung​

stopByRequestId​

func stopByRequestId(_ requestId: Int)

Stoppt die Haptik-Wiedergabe anhand der Request-ID.

Parameter​

  • requestId: Von der Haptik-Wiedergabefunktion zurückgegebene Request-ID.

Beispiel​

let requestId = kit.play(eventId: "shoot")
try await Task.sleep(nanoseconds: 2_000_000_000)
kit.stopByRequestId(requestId)

stopByEventId​

func stopByEventId(_ eventId: String)

Stoppt die gesamte Haptik-Wiedergabe für einen bestimmten Ereignisnamen.

Parameter​

  • eventId: Name des haptischen Ereignisses, das Sie stoppen möchten.

stopAll​

func stopAll()

Stoppt alle gerade abgespielten Haptiken.

pause​

func pause(_ eventId: String)

Pausiert die Wiedergabe eines bestimmten Ereignisses.

Parameter​

  • eventId: Name des haptischen Ereignisses, das Sie pausieren möchten.

resume​

func resume(_ eventId: String)

Setzt die pausierte Wiedergabe eines bestimmten Ereignisses fort.

Parameter​

  • eventId: Name des haptischen Ereignisses, das Sie fortsetzen möchten.

turnOffMotors​

func turnOffMotors()

Schaltet die Motoren aller verbundenen Geräte sofort ab.

Statusprüfung​

isPlaying​

func isPlaying() -> Bool

Prüft den gesamten Haptik-Wiedergabestatus. Funktioniert sowohl bei ereignisbasierter als auch bei direkter Wiedergabe.

isPlayingByRequestId​

func isPlayingByRequestId(_ requestId: Int) -> Bool

Prüft den Wiedergabestatus einer bestimmten Request-ID. Funktioniert sowohl bei ereignisbasierter als auch bei direkter Wiedergabe.

isPlayingByEventId​

func isPlayingByEventId(_ eventId: String) -> Bool

Prüft den Wiedergabestatus eines bestimmten Ereignisses.

getEventList​

func getEventList() -> [String]

Gibt die Namen der haptischen Ereignisse in Ihrer haptischen App zurück. Die Liste ist verfügbar, nachdem initialize abgeschlossen ist.

Geräteverwaltung​

Unter iOS und visionOS scannt das SDK Haptikgeräte über Bluetooth LE und verbindet sie. Unter macOS werden die Geräte vom bHaptics Player verwaltet: Die Scan- und Kopplungsfunktionen haben keine Wirkung, während getDevices und ping mit den Geräten arbeiten, die mit dem bHaptics Player verbunden sind.

scan​

func scan()

Startet die Suche nach bHaptics-Geräten in der Nähe. Gefundene Geräte werden an deviceStateUpdated übermittelt. Gekoppelte Geräte werden automatisch erneut verbunden, wenn sie gefunden werden.

Der Scan startet nur, wenn Bluetooth bereit ist. Rufen Sie diese Funktion auf, nachdem bleStateChange true gemeldet hat.

stopScan​

func stopScan()

Beendet den Scan. Geräte, die weder gekoppelt noch verbunden sind, werden aus der Geräteliste entfernt.

isScanning​

func isScanning() -> Bool

Prüft, ob das SDK gerade scannt.

toggleScanning​

func toggleScanning() -> Bool

Beendet den Scan, wenn das SDK gerade scannt, und startet ihn andernfalls.

Rückgabewert​

Ob das SDK nach dem Aufruf scannt.

pair​

func pair(device: BhapticsDevice)

Koppelt und verbindet das Gerät. Das SDK merkt sich gekoppelte Geräte über App-Starts hinweg.

Parameter​

unpair​

func unpair(device: BhapticsDevice)

Hebt die Kopplung des Geräts auf und trennt die Verbindung.

Parameter​

  • device: Das Gerät, dessen Kopplung aufgehoben werden soll.

getDevices​

func getDevices() -> [BhapticsDevice]

Gibt die gefundenen und gekoppelten Geräte zurück. Siehe BhapticsDevice.

ping​

@discardableResult
func ping(device: String) -> Bool

Sendet ein Ping an ein bestimmtes Gerät. Das Gerät vibriert kurz, sodass der Benutzer es identifizieren kann.

Parameter​

Rückgabewert​

Ob das Ping gesendet wurde.

Beispiel​

if let device = kit.getDevices().first {
    kit.ping(device: device.uuid)
}

pingAll​

@discardableResult
func pingAll() -> Bool

Sendet ein Ping an alle verbundenen Geräte.

Rückgabewert​

Ob das Ping gesendet wurde.

getBluetoothState​

func getBluetoothState() -> Int

Gibt den Bluetooth-Status zurück. Verwenden Sie dies, um festzustellen, warum keine Geräte gefunden werden.

WertStatus
0Unbekannt
1Wird zurückgesetzt
2Nicht unterstützt
3Nicht autorisiert (Bluetooth-Berechtigung wurde verweigert)
4Ausgeschaltet
5Eingeschaltet

Nur macOS​

isPlayerConnected​

func isPlayerConnected() -> Bool

Prüft den Verbindungsstatus mit dem bHaptics Player. Gibt unter iOS und visionOS immer false zurück.

onPlayerConnectionChanged​

var onPlayerConnectionChanged: ((Bool) -> Void)?

Wird im Main Thread aufgerufen, wenn sich der Verbindungsstatus mit dem bHaptics Player ändert. Nur unter macOS verfügbar.

Beispiel​

#if os(macOS)
kit.onPlayerConnectionChanged = { connected in
    print("bHaptics Player connected: \(connected)")
}
#endif

Typen​

BhapticsKitDelegate​

protocol BhapticsKitDelegate {
    func bHapticsKit(_ kit: BhapticsKit, bleStateChange state: Bool)
    func bHapticsKit(_ kit: BhapticsKit, deviceStateUpdated devices: [BhapticsDevice])
    func bHapticsKit(_ kit: BhapticsKit, didConnect device: BhapticsDevice)
    func bHapticsKit(_ kit: BhapticsKit, didDisconnect device: BhapticsDevice)
}

Empfängt unter iOS und visionOS Änderungen des Bluetooth- und Gerätestatus.

  • bleStateChange: Bluetooth ist bereit (true) oder nicht verfügbar (false).
  • deviceStateUpdated: Die Geräteliste hat sich geändert. Wird aufgerufen, wenn ein Gerät gefunden, gekoppelt, entkoppelt, verbunden oder getrennt wird.
  • didConnect: Ein Gerät wurde verbunden.
  • didDisconnect: Ein nicht gekoppeltes Gerät wurde getrennt.

BhapticsDevice​

Vom SDK gefundenes Haptikgerät.

EigenschaftTypBeschreibung
nameStringName des Geräts.
uuidStringEindeutige Kennung des Geräts. Auch als id verfügbar.
positionPositionTypeKörperteil, an dem das Gerät getragen wird.
batteryIntAkkustand in Prozent. -1, falls unbekannt.
connectedBoolOb das Gerät verbunden ist.
pairedBoolOb das Gerät gekoppelt ist.

BhapticsPosition​

Typ des Haptikgeräts. Verwenden Sie index, um ihn an Funktionen wie playDot, playPath und playGlove zu übergeben.

CaseindexGerät
.Vest0TactSuit
.ForearmL1TactSleeve(Left)
.ForearmR2TactSleeve(Right)
.Head3TactVisor
.HandL4Tactosy for Hands(Left)
.HandR5Tactosy for Hands(Right)
.FootL6Tactosy for Feet(Left)
.FootR7Tactosy for Feet(Right)
.GloveL8TactGlove(Left)
.GloveR9TactGlove(Right)
let position = BhapticsPosition.GloveL.index  // 8