Aller au contenu principal
Cette page a été traduite automatiquement et peut contenir des erreurs. Voir l’original en anglais

Références

La classe BhapticsKit fournit des fonctions pour contrôler les appareils haptiques bHaptics depuis Swift. Elle vous permet de connecter des appareils haptiques, de lire des motifs haptiques, de contrôler directement les moteurs des appareils et de gérer la lecture haptique.

import BhapticsPlugin

let kit = BhapticsKit()

Les fonctions qui lisent des haptiques retournent un ID de requête. Vous pouvez l'utiliser pour vérifier ou arrêter la lecture.

Cycle de vie​

init​

init()
init(delegate: BhapticsKitDelegate?)

Crée l'instance du SDK. Créez une seule instance et conservez-la pendant toute la durée de vie de votre app.

Sur iOS et visionOS, la création de l'instance démarre le Bluetooth, et le système demande à l'utilisateur l'autorisation Bluetooth.

Paramètres​

  • delegate (optionnel) : Reçoit les changements d'état du Bluetooth et des appareils. Voir BhapticsKitDelegate.

initialize​

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

Initialise l'environnement haptique. Cette fonction doit être appelée avant d'utiliser les fonctions liées aux événements.

  • Sur iOS et visionOS, elle télécharge depuis le serveur les événements haptiques de votre application haptique.
  • Sur macOS, elle se connecte à bHaptics Player. Si bHaptics Player est installé mais pas en cours d'exécution, elle lance bHaptics Player.

La version non async exécute la même initialisation en arrière-plan et ne retourne pas le résultat.

Paramètres​

  • appId : ID d'application créé dans bHaptics Developer Portal.
  • apiKey : Clé API créée dans bHaptics Developer Portal.
  • defaultSetting : Passez une chaîne vide ("").

Valeur de retour​

Statut de réussite de l'initialisation.

Exemple​

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

delegate​

var delegate: BhapticsKitDelegate?

Reçoit les changements d'état du Bluetooth et des appareils. Voir BhapticsKitDelegate.

Lecture haptique basée sur les événements​

Lit les motifs haptiques associés à des événements spécifiques (conçus dans bHaptics Designer/Portal). Ces fonctions sont recommandées pour la plupart des applications.

play​

func play(eventId: String) -> Int

Lit l'événement haptique prédéfini.

Paramètres​

  • eventId : Nom de l'événement haptique.

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

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

Lit l'événement haptique en ajustant la force, la Duration et la direction du retour haptique.

Paramètres​

  • eventId : Nom de l'événement haptique.
  • requestId (optionnel) : ID de requête à utiliser pour cette lecture. S'il est omis, un ID aléatoire est attribué.
  • intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
  • duration : Multiplicateur de Duration. (Défaut : 1.0)
  • angleX : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
  • offsetY : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

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

Lit les événements haptiques en boucle.

Paramètres​

  • eventId : Nom de l'événement haptique.
  • intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
  • duration : Multiplicateur de Duration. (Défaut : 1.0)
  • angleX : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
  • offsetY : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)
  • interval : Intervalle de temps entre les boucles, en millisecondes.
  • maxCount : Nombre de boucles.

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

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

Lit l'événement haptique à partir d'un instant précis. Utilisez cette fonction pour synchroniser les haptiques avec un média déjà en cours de lecture.

Paramètres​

  • eventId : Nom de l'événement haptique.
  • startMillis : Instant de début de la lecture, mesuré en millisecondes depuis le début de l'événement.
  • intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
  • duration : Multiplicateur de Duration. (Défaut : 1.0)
  • angleX : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
  • offsetY : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

// 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)

Lit les événements haptiques sans retourner d'ID de requête (fire-and-forget).

Paramètres​

  • eventId : Nom de l'événement haptique.
  • intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
  • duration : Multiplicateur de Duration. (Défaut : 1.0)
  • angleX : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
  • offsetY : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)

Exemple​

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

Lecture haptique directe​

Si vous souhaitez lire des retours haptiques sans événements, utilisez ces fonctions.

position est une valeur Int partagée avec les autres SDK bHaptics. Utilisez BhapticsPosition.index pour l'obtenir. Voir BhapticsPosition.

playDot​

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

Lit le retour haptique sur un actionneur haptique spécifique.

Paramètres​

  • position : Type d'appareil haptique pour la lecture. Pour plus d'informations, veuillez consulter ici.
    ValeurAppareilNombre de moteurs
    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 : La Duration du retour haptique, mesurée en millisecondes. Une valeur supérieure ou égale à 100 est recommandée.
  • arr : Définissez la longueur du tableau selon le nombre de moteurs de l'appareil. Les valeurs du tableau représentent l'Intensity des moteurs. Plage valide pour chaque valeur du tableau : [0 - 100]

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

// 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

Lit le retour haptique autour de coordonnées spécifiques. Contrairement à la fonction playDot qui spécifie l'Intensity haptique pour chaque actionneur individuellement, cette méthode spécifie l'Intensity haptique pour des coordonnées particulières.

Lors de la spécification de la position haptique, playDot offre un contrôle discret, tandis que playPath est plus continu. playDot attribue l'Intensity à des actionneurs individuels, tandis que playPath permet de spécifier l'Intensity pour des coordonnées spécifiques (entre 0 et 1 pour les axes X et Y), entraînant la vibration des actionneurs à proximité en conséquence.

Vous pouvez spécifier plusieurs coordonnées avec plusieurs intensités. Notez que tous les actionneurs autour de ces coordonnées dans le tableau s'activeront simultanément (en même temps), et non séquentiellement. De plus, la taille de tous les tableaux doit être identique.

En appelant continuellement cette fonction tout en modifiant progressivement les valeurs, vous pouvez obtenir l'effet d'un point haptique en mouvement.

Coordonnée

Paramètres​

  • position : Type d'appareil haptique pour la lecture. Voir le tableau dans playDot.
  • durationMillis : La Duration du retour haptique, mesurée en millisecondes. Une valeur supérieure ou égale à 100 est recommandée.
  • x : Tableau des coordonnées X pour l'effet haptique. Chaque valeur doit être dans la plage : [0.0 - 1.0]
  • y : Tableau des coordonnées Y pour l'effet haptique. Chaque valeur doit être dans la plage : [0.0 - 1.0]
  • intensity : Tableau des valeurs d'Intensity pour chaque coordonnée. La longueur doit correspondre au nombre de coordonnées. Chaque valeur doit être dans la plage : [0 - 100]

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

// 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

TactGlove uniquement. Lit le retour haptique dans TactGlove. Contrairement à l'utilisation de playDot, vous pouvez ajuster finement la Duration haptique et les changements d'Intensity de vibration. Cela permet une expression encore plus détaillée du retour haptique.

Passez un GlovePoint pour chaque moteur que vous souhaitez actionner. Au moins un point est nécessaire pour fonctionner.

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

Paramètres​

  • position : Type d'appareil haptique pour la lecture. Utilisez uniquement 8 ou 9.

    ValeurAppareil
    8TactGlove(Left)
    9TactGlove(Right)

  • points : Tableau de GlovePoint.

    • index : Index du moteur.

      IndexPosition du moteur
      0Bout du pouce
      1Bout de l'index
      2Bout du majeur
      3Bout de l'annulaire
      4Bout du petit doigt
      5Sur le poignet
      6Sur la paume (côté pouce)
      7Sur la paume (côté petit doigt)

    • intensity : Intensity du moteur. Plage valide : [0 - 100]

    • playTime : Intervalle de temps pour l'actionnement.

      ValeurDurée de lecture
      15ms
      210ms
      420ms
      630ms
      840ms

    • shape : Forme des changements d'Intensity haptique au fil du temps.

      ValeurForme d'onde
      0Intensity constante pendant toute la Duration
      1Commence à l'Intensity spécifiée et diminue de moitié
      2Commence à la moitié de l'Intensity spécifiée et augmente jusqu'à l'Intensity spécifiée.

  • frequency : Fréquence de vibration du moteur du poignet, en Hz. S'applique uniquement à TactGlove DK3. Passez 0 pour utiliser la valeur par défaut (80).

  • repeatCount : Nombre de répétitions.

Valeur de retour​

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture.

Exemple​

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)

Contrôle de la lecture​

stopByRequestId​

func stopByRequestId(_ requestId: Int)

Arrête la lecture haptique par ID de requête.

Paramètres​

  • requestId : ID de requête retourné par la fonction de lecture haptique.

Exemple​

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

stopByEventId​

func stopByEventId(_ eventId: String)

Arrête toute lecture haptique pour un nom d'événement spécifique.

Paramètres​

  • eventId : Nom de l'événement haptique que vous souhaitez arrêter.

stopAll​

func stopAll()

Arrête tous les retours haptiques en cours de lecture.

pause​

func pause(_ eventId: String)

Met en pause la lecture d'un événement spécifique.

Paramètres​

  • eventId : Nom de l'événement haptique que vous souhaitez mettre en pause.

resume​

func resume(_ eventId: String)

Reprend la lecture mise en pause d'un événement spécifique.

Paramètres​

  • eventId : Nom de l'événement haptique dont vous souhaitez reprendre la lecture.

turnOffMotors​

func turnOffMotors()

Éteint immédiatement les moteurs de tous les appareils connectés.

Vérification de l'état​

isPlaying​

func isPlaying() -> Bool

Vérifie l'état global de la lecture haptique. Fonctionne que la lecture soit basée sur des événements ou directe.

isPlayingByRequestId​

func isPlayingByRequestId(_ requestId: Int) -> Bool

Vérifie l'état de lecture d'un ID de requête spécifique. Fonctionne que la lecture soit basée sur des événements ou directe.

isPlayingByEventId​

func isPlayingByEventId(_ eventId: String) -> Bool

Vérifie l'état de lecture d'un événement spécifique.

getEventList​

func getEventList() -> [String]

Retourne les noms des événements haptiques de votre application haptique. La liste est disponible une fois initialize terminée.

Gestion des appareils​

Sur iOS et visionOS, le SDK scanne et connecte les appareils haptiques via Bluetooth LE. Sur macOS, les appareils sont gérés par bHaptics Player : les fonctions de scan et d'appairage n'ont aucun effet, tandis que getDevices et ping fonctionnent avec les appareils connectés à bHaptics Player.

scan​

func scan()

Démarre la recherche des appareils bHaptics à proximité. Les appareils détectés sont transmis à deviceStateUpdated. Les appareils appairés sont reconnectés automatiquement lorsqu'ils sont détectés.

Le scan ne démarre que lorsque le Bluetooth est prêt. Appelez cette fonction après que bleStateChange a signalé true.

stopScan​

func stopScan()

Arrête le scan. Les appareils qui ne sont ni appairés ni connectés sont retirés de la liste des appareils.

isScanning​

func isScanning() -> Bool

Vérifie si le SDK est en cours de scan.

toggleScanning​

func toggleScanning() -> Bool

Arrête le scan si le SDK est en cours de scan, et le démarre dans le cas contraire.

Valeur de retour​

Indique si le SDK est en cours de scan après l'appel.

pair​

func pair(device: BhapticsDevice)

Appaire et connecte l'appareil. Le SDK mémorise les appareils appairés d'un lancement de l'app à l'autre.

Paramètres​

unpair​

func unpair(device: BhapticsDevice)

Désappaire et déconnecte l'appareil.

Paramètres​

  • device : Appareil à désappairer.

getDevices​

func getDevices() -> [BhapticsDevice]

Retourne les appareils détectés et appairés. Voir BhapticsDevice.

ping​

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

Envoie un ping à un appareil spécifique. L'appareil vibre brièvement, ce qui permet à l'utilisateur de l'identifier.

Paramètres​

Valeur de retour​

Indique si le ping a été envoyé.

Exemple​

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

pingAll​

@discardableResult
func pingAll() -> Bool

Envoie un ping à tous les appareils connectés.

Valeur de retour​

Indique si le ping a été envoyé.

getBluetoothState​

func getBluetoothState() -> Int

Retourne l'état du Bluetooth. Utilisez cette fonction pour déterminer pourquoi aucun appareil n'est détecté.

ValeurÉtat
0Inconnu
1Réinitialisation en cours
2Non pris en charge
3Non autorisé (l'autorisation Bluetooth est refusée)
4Désactivé
5Activé

macOS uniquement​

isPlayerConnected​

func isPlayerConnected() -> Bool

Vérifie l'état de connexion avec bHaptics Player. Retourne toujours false sur iOS et visionOS.

onPlayerConnectionChanged​

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

Appelé sur le thread principal lorsque l'état de connexion avec bHaptics Player change. Disponible uniquement sur macOS.

Exemple​

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

Types​

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

Reçoit les changements d'état du Bluetooth et des appareils sur iOS et visionOS.

  • bleStateChange : Le Bluetooth est devenu prêt (true) ou indisponible (false).
  • deviceStateUpdated : La liste des appareils a changé. Appelée lorsqu'un appareil est détecté, appairé, désappairé, connecté ou déconnecté.
  • didConnect : Un appareil est connecté.
  • didDisconnect : Un appareil non appairé est déconnecté.

BhapticsDevice​

Appareil haptique détecté par le SDK.

PropriétéTypeDescription
nameStringNom de l'appareil.
uuidStringIdentifiant unique de l'appareil. Également disponible sous id.
positionPositionTypePartie du corps sur laquelle l'appareil est placé.
batteryIntNiveau de batterie en pourcentage. -1 s'il est inconnu.
connectedBoolIndique si l'appareil est connecté.
pairedBoolIndique si l'appareil est appairé.

BhapticsPosition​

Type d'appareil haptique. Utilisez index pour le passer à des fonctions telles que playDot, playPath et playGlove.

CasindexAppareil
.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