Implementieren Sie stückweise lineare Envelope-Effekte.

Stückweise lineare Hüllkurveneffekte (Piecewise Linear Envelope, PWLE) sind Folgen von Punkten, die die Vibrationsfrequenz und -beschleunigung im Zeitverlauf definieren. PWLEs bieten ein reichhaltigeres und dynamischeres haptisches Feedback.

Android 16 und höher bietet zwei APIs für App-Entwickler, mit denen PWLE-Effekte erstellt werden können:

• Basic PWLE API:Einfach, aber mit Einschränkungen. Gut für einen schnellen Einstieg. Diese API ist unter BasicEnvelopeBuilder verfügbar.
• Advanced PWLE API:Mehr Kontrolle und Flexibilität, erfordert Kenntnisse im Bereich Haptik und einige Vertrautheit mit der Hardware. Verfügbar unter WaveformEnvelopeBuilder.

Zur Unterstützung dieser APIs müssen Geräte die folgenden HAL-APIs implementieren:

• Resonanzfrequenz:Gibt die Resonanzfrequenz des Aktuators an.
• Frequency to Output Acceleration Mapping (FOAM) : Bietet eine Zuordnung der Vibrationsfrequenz zur maximal erreichbaren Ausgangsbeschleunigung für das Gerät.
• Compose PWLE:Spielt eine Vibration ab, die durch eine PWLE der Vibrationswellenform definiert ist.

Basic PWLE API

Um schnell PWLE-Effekte zu erstellen, ohne sich mit der Hardware oder den Nuancen der menschlichen Wahrnehmung auseinandersetzen zu müssen, können Entwickler die Basic PWLE API verwenden, die mit den folgenden Parametern definiert wird:

• Der Wert für die Intensität im Bereich von [0, 1] stellt die wahrgenommene Stärke der Vibration dar. Ein Wert von 0,5 wird beispielsweise als die Hälfte der globalen maximalen Intensität wahrgenommen, die mit dem Gerät erreicht werden kann.
• Der Wert für die Schärfe im Bereich von [0, 1] stellt die Schärfe der Vibration dar. Niedrigere Werte führen zu sanfteren Vibrationen, während höhere Werte ein schärferes Gefühl erzeugen.
• Die Dauer ist die Zeit in Millisekunden, die für den Übergang vom letzten PWLE-Punkt (d. h. dem Intensitäts- und Schärfepaar) zum neuen Punkt benötigt wird.

Hier ist ein Beispiel für eine Wellenform, bei der die Intensität über 500 ms von einer niedrigen Tonhöhe zu einer hohen Tonhöhe mit maximaler Stärke ansteigt und dann über 100 ms auf 0 (aus) abfällt:

VibrationEffect effect = new VibrationEffect.BasicEnvelopeBuilder()
          .setInitialSharpness(0.0f)
          .addControlPoint(1.0f, 1.0f, 500)
          .addControlPoint(0.0f, 1.0f, 100)
          .build();

Einschränkungen

Um ein sanftes und nahtloses haptisches Erlebnis zu schaffen, müssen PWLE-Effekte mit einer Intensität von 0,0 beginnen und enden. Die API erzwingt dies, indem sie die Startintensität auf 0 festlegt und eine Ausnahme auslöst, wenn die Endintensität nicht 0 ist. Diese Einschränkung verhindert unerwünschte dynamische Effekte bei den Vibrationen aufgrund von Diskontinuitäten in der Amplitude, die sich negativ auf die haptische Wahrnehmung des Nutzers auswirken können.

Um eine konsistente Darstellung von PWLE-Effekten im gesamten Android-Ökosystem zu gewährleisten, muss das Framework auf Geräten, die diese Funktion unterstützen, eine Mindestdauer von 20 ms zwischen PWLE-Punkten und mindestens 16 Punkten für PWLE-Effekte verarbeiten können. Diese Anforderungen werden durch VTS-Tests erzwungen, um zuverlässige PWLE-Effekte auf allen Android-Geräten zu gewährleisten.

Advanced PWLE API

Entwickler mit fortgeschrittenen Kenntnissen im Bereich Haptik können PWLE-Effekte anhand der folgenden Kriterien definieren:

• Der Wert für die Amplitude im Bereich von [0, 1] stellt die erreichbare Stärke bei einer bestimmten Frequenz dar, die durch die FOAM des Geräts bestimmt wird. Ein Wert von 0,5 erzeugt beispielsweise die Hälfte der maximalen Ausgangsbeschleunigung, die bei der angegebenen Frequenz erreicht werden kann.
• Die Frequenz wird direkt in Hertz angegeben.
• Die Dauer ist die Zeit in Millisekunden, die für den Übergang vom letzten PWLE-Punkt zum neuen Punkt benötigt wird.

Hier ist ein Beispiel für eine Wellenform, bei der ein Vibrator über 100 ms von aus auf volle Amplitude bei 120 Hz ansteigt, diesen Zustand 200 ms lang beibehält und dann über 100 ms wieder abfällt:

VibrationEffect effect = new VibrationEffect.WaveformEnvelopeBuilder()
          .addControlPoint(1.0f, 120f, 100)
          .addControlPoint(1.0f, 120f, 200)
          .addControlPoint(0.0f, 120f, 100)
          .build();

Einschränkungen

Das Framework ändert die vom Entwickler angeforderten Frequenz- und Amplitudenwerte nicht, fügt aber einen Startpunkt mit der Amplitude 0 hinzu, um einen sanften Übergang zu gewährleisten.

Entwickler sind dafür verantwortlich, dass die in ihren PWLE-Effekten angegebene Frequenz innerhalb des vom Gerät unterstützten Bereichs liegt, wie in der FOAM des Geräts definiert. Wenn die Werte diese Grenzwerte überschreiten, gibt das Gerät keine Vibration aus.

Frequency to Output Acceleration Mapping (FOAM)

Eine genaue Darstellung der Frequenz-zu-Ausgangsbeschleunigungs-Funktionen eines Geräts ist für die Unterstützung der PWLE-APIs unerlässlich. In diesem Abschnitt wird die Bedeutung dieser Daten, ihre Verwendung durch PWLE-APIs und der Prozess ihrer Generierung beschrieben.

Zuordnung verstehen

Geräte, die PWLE-Effekte unterstützen, müssen eine Frequency to Output Acceleration Map (FOAM) bereitstellen. Die FOAM ist eine Datenstruktur, die von der HAL generiert wird und die Vibrationsfrequenz (in Hertz) der maximal erreichbaren Ausgangsbeschleunigung des Aktuators (in G peak) bei dieser Frequenz zuordnet. Diese Zuordnung ist entscheidend, um zu verstehen, wie die Vibrationsausgabe für den unterstützten Frequenzbereich variiert, und um die Basic PWLE API zu definieren.

Die folgende Grafik zeigt ein Beispiel für eine FOAM für einen typischen Resonanzaktuator, wobei die Eingangsspannung um die Resonanzfrequenz begrenzt ist, um den Motor zu schützen:

Abbildung 1 : Beispiel für eine FOAM für einen typischen Resonanzaktuator.

Die FOAM erfüllt drei Hauptzwecke:

• Definition des vollständigen Frequenzbereichs:Die FOAM definiert den vollständigen Frequenzbereich des Geräts, indem sie die unterstützten Mindest- und Höchstwerte für die Vibrationsfrequenz angibt.
• Definition der Intensitäts- und Schärfewerte:Die Basic PWLE API arbeitet mit einer Skala für die menschliche Wahrnehmung von Intensität und Schärfe, die dann mithilfe der Ausgangsbeschleunigungswerte in der FOAM den Hardwareparametern für Frequenz und Amplitude zugeordnet werden. Diese Zuordnung trägt dazu bei, dass die haptischen Effekte entsprechend den Hardwarefunktionen dargestellt werden. Der Schärfebereich wird durch den minimal wahrnehmbaren Schwellenwert definiert und entspricht den Frequenzen, bei denen das Gerät haptische Effekte erzeugen kann, die Nutzer spüren können. Das Framework ordnet die Intensitätswerte basierend auf der Zielausgangsbeschleunigung bei der ausgewählten Frequenz der Amplitude zu. So wird sichergestellt, dass die ausgewählte Intensität erreicht wird, ohne die Funktionen des Geräts zu überschreiten.
• Offenlegung der Hardwarefunktionen: Die FOAM wird Entwicklern in VibratorFrequencyProfile zur Verfügung gestellt und enthält das vollständige Dataset für die Zuordnung von Frequenz zu Ausgangsbeschleunigung, in dem einige der haptischen Funktionen des Geräts beschrieben werden. Mit diesen Daten können Entwickler, die die Advanced PWLE API verwenden, benutzerdefinierte Vibrationseffekte erstellen, die über die vom Framework definierten grundlegenden Intensitäts- und Schärfebereiche hinausgehen.

FOAM und Basic PWLE API

Die FOAM spielt eine wichtige Rolle bei der Gestaltung von Vibrationseffekten. Sie wird verwendet, um den Schärfebereich für die Basic Envelope API zu berechnen, damit Vibrationen für den Nutzer wahrnehmbar sind. Dieser Bereich entspricht den Frequenzen, bei denen die Ausgangsbeschleunigung zuerst 10 dB über dem Schwellenwert für die menschliche Wahrnehmung (d. h. dem minimal wahrnehmbaren Pegel) liegt, bis zu dem Punkt, an dem die Ausgangsbeschleunigung zuletzt über diesem Schwellenwert liegt. Dieser Bereich muss die Resonanzfrequenz des Aktuators enthalten.

Außerdem verwendet das Framework die FOAM-Daten, um die in der Basic PWLE API verwendeten Intensitäts- und Schärfewerte den entsprechenden Amplituden- und Frequenzwerten zuzuordnen. Diese Zuordnung trägt dazu bei, dass auf verschiedenen Geräten wahrnehmbares haptisches Feedback erzeugt wird.

VTS-Tests sorgen dafür, dass Geräte, die Hüllkurveneffekte unterstützen, einen nicht leeren Frequenzbereich haben, der wahrnehmbare Vibrationen erzeugt, und dass der Bereich die Resonanzfrequenz des Aktuators enthält. So wird sichergestellt, dass das Gerät Vibrationen mit ausreichender Intensität erzeugen kann, die von Nutzern deutlich wahrgenommen werden.

FOAM und Advanced PWLE API

FOAM wird Entwicklern über VibratorFrequencyProfile mit den folgenden Informationen zur Verfügung gestellt:

• Frequenzbereich: Entwickler können die minimalen und maximalen unterstützten Frequenzen des Geräts in Hertz mit getMinFrequencyHz bzw. getMaxFrequencyHz abrufen.
• Maximale Ausgangsbeschleunigung: Die maximal erreichbare Ausgangs beschleunigung des Geräts (in G) ist über getMaxOutputAccelerationGs verfügbar.
• Zuordnung von Frequenz zu Ausgangsbeschleunigung: getFrequenciesOutputAcceleration bietet die Zuordnung von Frequenz zu Ausgangsbeschleunigung, wie sie in der HAL implementiert ist.

Entwickler können diese Informationen verwenden, wenn sie mit der Advanced PWLE API Hüllkurveneffekte erstellen. Wenn sie beispielsweise eine Ausgangsbeschleunigung (in G) angeben, müssen sie sie auf einen Wert im Bereich [0,0, 1,0] normalisieren, relativ zur maximalen Ausgangsbeschleunigung des Geräts.

Mit der Advanced PWLE API können Entwickler den gesamten Frequenzbereich nutzen. Daher ist es entscheidend, dass die bereitgestellten FOAM-Daten für den Vibrator sicher sind und seine Funktionen nicht überschreiten.

Schwellenwert für die menschliche Wahrnehmung

Der Schwellenwert für die menschliche Wahrnehmung bezieht sich auf die minimale Beschleunigung einer Vibration, die eine Person zuverlässig erkennen kann. Dieser Pegel variiert je nach Vibrationsfrequenz.

Die folgende Grafik zeigt den Schwellenwert für die menschliche haptische Wahrnehmung¹ in Beschleunigung als Funktion der zeitlichen Frequenz:

Abbildung 2 : Schwellenwert für die menschliche haptische Wahrnehmung.

Damit Nutzer die haptischen Effekte konsistent spüren können, wird in VTS-Tests geprüft, ob Geräte mit Hüllkurvenfunktionen einen Frequenzbereich haben, der Vibrationsamplituden erzeugen kann, die den Schwellenwert für die menschliche Wahrnehmung um 10 dB übersteigen.

Wahrgenommene Vibrationsintensität im Vergleich zur Vibrationsbeschleunigungsamplitude

Die menschliche Wahrnehmung der Vibrationsintensität (ein Wahrnehmungsmaß) steigt nicht linear mit der Vibrationsamplitude (einem physikalischen Parameter) an. Die PWLE API geht davon aus, dass Designer oder Entwickler bei Änderungen der Vibrationsstärke erwarten, dass die wahrgenommene Intensität einer PWLE folgt. Die wahrgenommene Intensität wird durch den Empfindungspegel (Sensation Level, SL) charakterisiert, der als dB über dem Schwellenwert bei derselben Frequenz definiert ist. Die Vibrationsbeschleunigungsamplitude (in G peak) kann also so berechnet werden:

\(Amplitude(G) =10^\frac{Amplitude(db)}{20}\)

Dabei ist die Amplituden-dB-Zahl die Summe aus SL und Schwellenwert (der Wert entlang der Ordinate in der folgenden Grafik) bei einer bestimmten Frequenz.

So stellt die PWLE API sicher, dass sich die wahrgenommene Intensität zwischen aufeinanderfolgenden Paaren von Kontrollpunkten linear ändert.

Die folgende Grafik zeigt die Vibrationsbeschleunigungspegel² bei 10, 20, 30, 40 und 50 dB SL sowie den Schwellenwert für die menschliche haptische Wahrnehmung (0 dB SL) als Funktion der zeitlichen Frequenz.

Abbildung 3 : Vibrationsbeschleunigungspegel.

Kurve für Frequenz zu maximaler Ausgangsbeschleunigung bestimmen

In diesem Abschnitt finden Sie eine allgemeine Anleitung, wie Sie die Kurve für Frequenz zu maximaler Ausgangsbeschleunigung vom Gerät abrufen, mit der Sie die FOAM-Daten generieren.

Kurve für maximale Spannung (V) abrufen

V ist die maximale Spannung, die sicher auf den Vibrator im gesamten Betriebsfrequenzbereich angewendet werden kann. So wird sichergestellt, dass der Vibrator innerhalb sicherer Grenzwerte arbeitet, Schäden vermieden und die Vibrationsausgabe maximiert wird.

Wenn die Hardware eine Funktion zur Spannungsbegrenzung enthält, verwenden Sie sie, um die maximal erreichbare Spannung im gesamten unterstützten Frequenzbereich direkt zu messen.

Maximale Beschleunigung (M) berechnen

M ist die maximale Beschleunigung, die mit verschiedenen Methoden berechnet werden kann. In diesem Abschnitt wird eine Methode für Geräte mit linearen Resonanzaktuatoren (Linear Resonant Actuators, LRAs) beschrieben.

Bei dieser Methode wird die maximale angelegte Spannung bei einer bestimmten Frequenz in einen entsprechenden Wert für die maximale Beschleunigung umgewandelt, ausgedrückt in G peak.

Die für diese Umwandlung verwendete Kernformel lautet:

\(\text{Accel}(w)= (\text{Vsys}\times\text{BLsys}\times\text{Loc_coeff}/\text{Rsys}/\text{MPhone})\times{w^2}/\text{Psys_abs}/{9.81}\)

Dabei gilt:

Vsys: Tatsächlicher Spannungspegel, der auf den haptischen Aktuator angewendet wird

BLsys: Produkt aus Magnetfeldstärke (B) und Leiterlänge (L) des Vibrationsmotors

Loc_coeff: Standortkoeffizient zur Umwandlung der Beschleunigung auf Modulebene in die Beschleunigung auf Geräteebene

Rsys: Elektrischer Widerstand der Spule des Vibrationsmotors

MPhone: Masse des Geräts (z. B. Smartphone)

w: Winkelfrequenz (Radiant pro Sekunde) des Ansteuersignals, berechnet als:

\(w = 2 \pi f\)

Psys_abs: Amplitudenreaktion eines Massen-, Dämpfer- und Federsystems zweiter Ordnung, berechnet als:

\(\text{Psys_abs} = (\text{Wnsys}^2-w^2)^2+({w}\times(\text{Wnsys}/\text{Qsys}))^2\)

Wnsys: Eigenfrequenz des Vibrationssystems

Qsys: Gütefaktor des Vibrationssystems

Loc_coeff ist das Verhältnis der auf Geräteebene gemessenen Beschleunigung zur auf Modulebene gemessenen Beschleunigung. Dieses Verhältnis wird verwendet, um Beschleunigungswerte auf Modulebene in entsprechende Beschleunigungswerte auf Geräteebene umzuwandeln. Auf Geräteebene wird die Beschleunigung aufgrund der Winkelbeschleunigung der Modulbewegung verstärkt. Dieser Koeffizient berücksichtigt diese Art von Effekt. Er wird so berechnet:

\(\text{Loc_coeff} = \text{phone_acceleration} / \text{module_acceleration}\)

Wenn die Modulbeschleunigung beispielsweise 1 g und die Gerätebeschleunigung 2,5 g beträgt, dann ist Loc_coeff = 2,5. Das bedeutet eine 2,5-fache Verstärkung.

Das Android-Framework verwendet die Frequenz in Hertz. Daher muss die HAL die Frequenzeinheit beim Generieren der FOAM-Daten von Radiant pro Sekunde in Hertz umwandeln.

FOAM-Kurve generieren

Kombinieren Sie die Kurve für die maximale Spannung (V) und die Beschleunigungsberechnung (M), um die FOAM-Kurve zu bestimmen:

• Suchen Sie für jede Frequenz (f) im gewünschten Bereich die entsprechende maximale Spannung V(f) aus der Kurve für die maximale Spannung.
• Berechnen Sie die maximale Beschleunigung bei dieser Frequenz mit der Gleichung oben, indem Sie V(f) für Vsys und die entsprechende f für w einsetzen. So erhalten Sie M(V(f), f).
• Diese berechnete Beschleunigung ist Ihr FOAM(f)-Wert.

FOAM-Daten bereitstellen

Nachdem die FOAM-Kurve generiert wurde, stellt die HAL die Kurve als Liste von FrequencyAccelerationMapEntry-Objekten dar. Jeder Eintrag definiert einen Punkt in der Zuordnung und gibt eine Frequenz (in Hertz) und die entsprechende maximale Ausgangsbeschleunigung (in G peak) an.

Um die Genauigkeit der linearen Interpolation bei der Bestimmung von Zwischenbeschleunigungswerten zu optimieren, empfehlen wir, eine hohe Frequenzauflösung um die Frequenz mit der maximalen Ausgangsbeschleunigung zu definieren. Verwenden Sie beispielsweise Schritte von 1 Hz im Bereich von +/- 10 Hz dieser Frequenz.

Gerätefunktionen und -einschränkungen

Für Android 16 und höher enthält Android HAL-APIs, mit denen Entwickler ihre PWLE-Effekte optimieren und die Kompatibilität auf verschiedenen Geräten gewährleisten können. Mit diesen APIs können die PWLE-Funktionen des Geräts abgefragt werden. Diese Methoden liefern Informationen zu den Einschränkungen des Geräts, z. B. zur minimalen oder maximalen Dauer von PWLE-Primitiven und zur Anzahl der in einer PWLE-Komposition zulässigen Primitiven.

Die HAL-APIs umfassen:

• CAP_COMPOSE_PWLE_EFFECTS_V2: Wird von IVibrator.getCapabilities zurückgegeben, wenn das Gerät diese Funktion unterstützt.
• getFrequencyToOutputAccelerationMap: Ruft die FOAM-Daten ab.
• getPwleV2PrimitiveDurationMinMillis: Ruft die minimale Dauer für ein beliebiges PWLE-Primitiv in Millisekunden ab.
• getPwleV2PrimitiveDurationMaxMillis: Ruft die maximale Dauer für ein beliebiges PWLE-Primitiv in Millisekunden ab.
• getPwleV2CompositionSizeMax: Ruft die maximale Anzahl von PWLE-Primitiven ab, die von IVibrator.composePwleV2 unterstützt werden.

Diese Informationen werden Entwicklern zur Verfügung gestellt, damit sie ihre Effekte an die spezifischen Funktionen des Zielgeräts anpassen können, insbesondere bei Verwendung der Advanced PWLE API.

Das Framework verwendet diese APIs auch bei der Verarbeitung von Effekten, die mit der Basic PWLE API erstellt wurden. Wenn ein Effekt die Einschränkungen des Geräts überschreitet (z. B. zu viele PWLE-Punkte oder eine Dauer, die das Maximum überschreitet), passt das Framework den Effekt automatisch an die zulässigen Grenzen an. Bei diesem Anpassungsprozess wird versucht, die ursprüngliche Absicht und das ursprüngliche Gefühl des Designs so weit wie möglich beizubehalten.