Saltar al contenido principal
Esta página se tradujo automáticamente y puede contener errores. Ver el original en inglés

Referencias

La clase BhapticsKit proporciona funciones para controlar dispositivos hápticos de bHaptics desde Swift. Le permite conectar dispositivos hápticos, reproducir patrones hápticos, controlar directamente los motores del dispositivo y gestionar la reproducción háptica.

import BhapticsPlugin

let kit = BhapticsKit()

Las funciones que reproducen háptica devuelven un ID de solicitud. Puede usarlo para comprobar o detener la reproducción.

Ciclo de vida​

init​

init()
init(delegate: BhapticsKitDelegate?)

Crea la instancia del SDK. Cree una sola instancia y consérvela durante todo el ciclo de vida de su aplicación.

En iOS y visionOS, al crear la instancia se inicia Bluetooth y el sistema solicita al usuario el permiso de Bluetooth.

Parámetros​

  • delegate (opcional): recibe los cambios de estado de Bluetooth y de los dispositivos. Consulte BhapticsKitDelegate.

initialize​

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

Inicializa el entorno háptico. Esta función debe llamarse antes de usar las funciones relacionadas con eventos.

  • En iOS y visionOS, descarga desde el servidor los eventos hápticos de su aplicación háptica.
  • En macOS, se conecta a bHaptics Player. Si bHaptics Player está instalado pero no en ejecución, inicia bHaptics Player.

La versión no async ejecuta la misma inicialización en segundo plano y no devuelve el resultado.

Parámetros​

  • appId: ID de la aplicación creado en bHaptics Developer Portal.
  • apiKey: API Key creada en bHaptics Developer Portal.
  • defaultSetting: pase una cadena vacía ("").

Valor de retorno​

Estado de éxito de la inicialización.

Ejemplo​

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

delegate​

var delegate: BhapticsKitDelegate?

Recibe los cambios de estado de Bluetooth y de los dispositivos. Consulte BhapticsKitDelegate.

Reproducción de háptica basada en eventos​

Reproduce patrones hápticos vinculados a eventos específicos (diseñados en bHaptics Designer/Portal). Estas son las funciones recomendadas para la mayoría de las aplicaciones.

play​

func play(eventId: String) -> Int

Reproduce el evento háptico predefinido.

Parámetros​

  • eventId: nombre del evento háptico.

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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

Reproduce el evento háptico ajustando la intensidad, la Duration y la dirección de la háptica.

Parámetros​

  • eventId: nombre del evento háptico.
  • requestId (opcional): ID de solicitud que se usará para esta reproducción. Si se omite, se asigna un ID aleatorio.
  • intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
  • duration: multiplicador de la Duration. (Predeterminado: 1.0)
  • angleX: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
  • offsetY: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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

Reproduce eventos hápticos en bucle.

Parámetros​

  • eventId: nombre del evento háptico.
  • intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
  • duration: multiplicador de la Duration. (Predeterminado: 1.0)
  • angleX: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
  • offsetY: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)
  • interval: intervalo de tiempo entre bucles, en milisegundos.
  • maxCount: número de bucles.

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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

Reproduce el evento háptico desde un momento específico. Úselo para sincronizar la háptica con contenido multimedia que ya se está reproduciendo.

Parámetros​

  • eventId: nombre del evento háptico.
  • startMillis: tiempo de inicio de la reproducción, medido en milisegundos desde el comienzo del evento.
  • intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
  • duration: multiplicador de la Duration. (Predeterminado: 1.0)
  • angleX: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
  • offsetY: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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

Reproduce eventos hápticos sin devolver un ID de solicitud (fire-and-forget).

Parámetros​

  • eventId: nombre del evento háptico.
  • intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
  • duration: multiplicador de la Duration. (Predeterminado: 1.0)
  • angleX: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
  • offsetY: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)

Ejemplo​

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

Reproducción directa de háptica​

Si desea reproducir háptica sin eventos, use estas funciones.

position es un valor Int compartido con los demás SDK de bHaptics. Use BhapticsPosition.index para obtenerlo. Consulte BhapticsPosition.

playDot​

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

Reproduce retroalimentación háptica en el actuador háptico específico.

Parámetros​

  • position: tipo de dispositivo háptico a reproducir. Para obtener más información, consulte aquí.
    ValorDispositivoNúmero de motores
    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 de la háptica, medida en milisegundos. Se recomienda un valor mayor o igual a 100.
  • arr: asigne la longitud del array según el número de motores del dispositivo. Los valores del array representan la Intensity de los motores. El rango válido para cada valor del array es: [0 - 100]

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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

Reproduce háptica alrededor de coordenadas específicas. A diferencia de la función playDot, que especifica la Intensity háptica para cada actuador háptico de forma individual, este método especifica la Intensity háptica para coordenadas concretas.

Al especificar la posición de la háptica, playDot ofrece un control discreto, mientras que playPath es más continuo. playDot asigna la Intensity a actuadores individuales, mientras que playPath permite especificar la Intensity para coordenadas concretas (entre 0 y 1 tanto para el eje X como para el Y), haciendo que los actuadores cercanos vibren en consecuencia.

Puede colocar varias coordenadas con varias intensidades. Tenga en cuenta que todos los actuadores alrededor de estas coordenadas del array se activarán simultáneamente (al mismo tiempo), no de forma secuencial. Además, el tamaño de todos los arrays debe ser el mismo.

Al llamar continuamente a esta función mientras cambia los valores gradualmente, puede lograr el efecto de un punto háptico en movimiento.

Coordenada

Parámetros​

  • position: tipo de dispositivo háptico a reproducir. Consulte la tabla en playDot.
  • durationMillis: la Duration de la háptica, medida en milisegundos. Se recomienda un valor mayor o igual a 100.
  • x: array de coordenadas X para el efecto háptico. Cada valor debe estar en el rango: [0.0 - 1.0]
  • y: array de coordenadas Y para el efecto háptico. Cada valor debe estar en el rango: [0.0 - 1.0]
  • intensity: array de valores de Intensity para cada coordenada. La longitud debe coincidir con el número de coordenadas. Cada valor debe estar en el rango: [0 - 100]

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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

Solo TactGlove. Reproduce háptica en TactGlove. A diferencia del uso de playDot, puede ajustar con precisión la Duration de la háptica y los cambios de Intensity de la vibración. Esto permite una expresión aún más detallada de la retroalimentación háptica.

Pase un GlovePoint por cada motor que desee accionar. Se requiere al menos un punto para que funcione.

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

Parámetros​

  • position: tipo de dispositivo háptico a reproducir. Use solo 8 o 9.

    ValorDispositivo
    8TactGlove(Left)
    9TactGlove(Right)

  • points: array de GlovePoint.

    • index: índice del motor.

      ÍndiceEl motor está ubicado en…
      0Punta del pulgar
      1Punta del dedo índice
      2Punta del dedo medio
      3Punta del dedo anular
      4Punta del dedo meñique
      5En la muñeca
      6En la palma (lado del pulgar)
      7En la palma (lado del dedo meñique)

    • intensity: Intensity del motor. Rango válido: [0 - 100]

    • playTime: intervalo de tiempo de accionamiento.

      ValorPlaytimes
      15ms
      210ms
      420ms
      630ms
      840ms

    • shape: forma del cambio de Intensity háptica a lo largo del tiempo.

      ValorForma de onda
      0Intensity constante durante la Duration
      1Comienza con la Intensity especificada y disminuye a la mitad
      2Comienza con la mitad de la Intensity especificada y aumenta hasta la especificada.

  • frequency: frecuencia de vibración del motor de la muñeca, en Hz. Solo se aplica a TactGlove DK3. Pase 0 para usar el valor predeterminado (80).

  • repeatCount: número de repeticiones.

Valor de retorno​

ID de solicitud. Puede usarlo para detener la reproducción.

Ejemplo​

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)

Control de la reproducción​

stopByRequestId​

func stopByRequestId(_ requestId: Int)

Detiene la reproducción háptica por ID de solicitud.

Parámetros​

  • requestId: ID de solicitud devuelto por la función de reproducción háptica.

Ejemplo​

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

stopByEventId​

func stopByEventId(_ eventId: String)

Detiene toda la reproducción háptica de un nombre de evento específico.

Parámetros​

  • eventId: nombre del evento háptico que desea detener.

stopAll​

func stopAll()

Detiene toda la háptica que se está reproduciendo actualmente.

pause​

func pause(_ eventId: String)

Pausa la reproducción de un evento específico.

Parámetros​

  • eventId: nombre del evento háptico que desea pausar.

resume​

func resume(_ eventId: String)

Reanuda la reproducción pausada de un evento específico.

Parámetros​

  • eventId: nombre del evento háptico que desea reanudar.

turnOffMotors​

func turnOffMotors()

Apaga inmediatamente los motores de todos los dispositivos conectados.

Comprobación de estado​

isPlaying​

func isPlaying() -> Bool

Comprueba el estado general de la reproducción háptica. Funciona tanto en la reproducción basada en eventos como en la reproducción directa.

isPlayingByRequestId​

func isPlayingByRequestId(_ requestId: Int) -> Bool

Comprueba el estado de reproducción de un ID de solicitud específico. Funciona tanto en la reproducción basada en eventos como en la reproducción directa.

isPlayingByEventId​

func isPlayingByEventId(_ eventId: String) -> Bool

Comprueba el estado de reproducción de un evento específico.

getEventList​

func getEventList() -> [String]

Devuelve los nombres de los eventos hápticos de su aplicación háptica. La lista está disponible después de que initialize finalice.

Gestión de dispositivos​

En iOS y visionOS, el SDK escanea y conecta los dispositivos hápticos mediante Bluetooth LE. En macOS, los dispositivos los gestiona bHaptics Player: las funciones de escaneo y emparejamiento no tienen efecto, mientras que getDevices y ping funcionan con los dispositivos conectados a bHaptics Player.

scan​

func scan()

Inicia el escaneo de dispositivos bHaptics cercanos. Los dispositivos encontrados se entregan a deviceStateUpdated. Los dispositivos emparejados se vuelven a conectar automáticamente cuando se encuentran.

El escaneo solo se inicia cuando Bluetooth está listo. Llame a esta función después de que bleStateChange informe true.

stopScan​

func stopScan()

Detiene el escaneo. Los dispositivos que no están emparejados ni conectados se eliminan de la lista de dispositivos.

isScanning​

func isScanning() -> Bool

Comprueba si el SDK está escaneando.

toggleScanning​

func toggleScanning() -> Bool

Detiene el escaneo si el SDK está escaneando y, en caso contrario, lo inicia.

Valor de retorno​

Si el SDK está escaneando después de la llamada.

pair​

func pair(device: BhapticsDevice)

Empareja y conecta el dispositivo. El SDK recuerda los dispositivos emparejados entre inicios de la aplicación.

Parámetros​

unpair​

func unpair(device: BhapticsDevice)

Desempareja y desconecta el dispositivo.

Parámetros​

  • device: dispositivo que se va a desemparejar.

getDevices​

func getDevices() -> [BhapticsDevice]

Devuelve los dispositivos encontrados y emparejados. Consulte BhapticsDevice.

ping​

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

Envía un ping a un dispositivo específico. El dispositivo vibra brevemente para que el usuario pueda identificarlo.

Parámetros​

Valor de retorno​

Si se envió el ping.

Ejemplo​

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

pingAll​

@discardableResult
func pingAll() -> Bool

Envía un ping a todos los dispositivos conectados.

Valor de retorno​

Si se envió el ping.

getBluetoothState​

func getBluetoothState() -> Int

Devuelve el estado de Bluetooth. Úselo para saber por qué no se encuentran dispositivos.

ValorEstado
0Desconocido
1Restableciendo
2No compatible
3No autorizado (se denegó el permiso de Bluetooth)
4Apagado
5Encendido

Solo macOS​

isPlayerConnected​

func isPlayerConnected() -> Bool

Comprueba el estado de conexión con bHaptics Player. Siempre devuelve false en iOS y visionOS.

onPlayerConnectionChanged​

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

Se llama en el hilo principal cuando cambia el estado de conexión con bHaptics Player. Disponible solo en macOS.

Ejemplo​

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

Tipos​

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

Recibe los cambios de estado de Bluetooth y de los dispositivos en iOS y visionOS.

  • bleStateChange: Bluetooth pasó a estar listo (true) o no disponible (false).
  • deviceStateUpdated: la lista de dispositivos cambió. Se llama cuando un dispositivo se encuentra, se empareja, se desempareja, se conecta o se desconecta.
  • didConnect: se conectó un dispositivo.
  • didDisconnect: se desconectó un dispositivo que no está emparejado.

BhapticsDevice​

Dispositivo háptico encontrado por el SDK.

PropiedadTipoDescripción
nameStringNombre del dispositivo.
uuidStringIdentificador único del dispositivo. También disponible como id.
positionPositionTypeParte del cuerpo en la que se coloca el dispositivo.
batteryIntNivel de batería en porcentaje. -1 si se desconoce.
connectedBoolSi el dispositivo está conectado.
pairedBoolSi el dispositivo está emparejado.

BhapticsPosition​

Tipo de dispositivo háptico. Use index para pasarlo a funciones como playDot, playPath y playGlove.

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