Implementieren Sie stückweise lineare Envelope-Effekte.

PWLE-Effekte (Piecewise Linear Envelope) sind Folgen von Punkten, die die Schwingungsfrequenz und Beschleunigung im Zeitverlauf definieren. PWLEs bieten ein detaillierteres und dynamischeres haptisches Feedback.

In Android 16 und höher stehen zwei App-Entwickler-APIs zur Verfügung, mit denen sich PWLE-Effekte erstellen lassen:

• Basic PWLE API:Einfach, aber mit Einschränkungen. Gut für einen schnellen Einstieg. Sie finden es unter BasicEnvelopeBuilder.
• Erweiterte PWLE-API:Mehr Kontrolle und Flexibilität, erfordert Haptikkenntnisse und einige Hardwarekenntnisse. Verfügbar unter WaveformEnvelopeBuilder.

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

• Häufigkeit für die Ausgabe der Beschleunigungszuordnung (Frequency to Output Acceleration Mapping, FOAM): Bietet eine Zuordnung der Vibrationsfrequenz zur maximal erreichbaren Ausgabebeschleunigung für das Gerät.
• PWLE erstellen:Gibt eine Vibration wieder, die durch eine PWLE der Vibrationswellenform definiert wird.

Einfache PWLE API

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

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

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

Damit die haptische Wahrnehmung reibungslos und nahtlos ist, 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.

Damit der PWLE-Effekt im gesamten Android-Ökosystem einheitlich gerendert wird, muss das Framework sicherstellen, dass Geräte, die diese Funktion unterstützen, eine Mindestdauer von 10 ms zwischen PWLE-Punkten und mindestens 16 Punkte für PWLE-Effekte verarbeiten können. Diese Anforderungen werden durch VTS-Tests durchgesetzt, um zuverlässige PWLE-Effekte auf Android-Geräten zu gewährleisten.

Erweiterte PWLE API

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

• Der Amplitude-Wert im Bereich [0, 1] stellt die erreichbare Stärke bei einer bestimmten Frequenz dar, die vom Geräte-FOAM bestimmt wird. Ein Wert von 0,5 führt beispielsweise zu einer Beschleunigung der Ausgabe, die halb so hoch ist wie die maximale Beschleunigung, die bei der angegebenen Häufigkeit erreicht werden kann.
• Die Frequenz wird direkt in Hertz angegeben.
• Dauer ist die Zeit, die für den Übergang vom letzten PWLE-Punkt zum neuen Punkt benötigt wird, in Millisekunden.

Hier ist ein Beispiel für eine Wellenform, die einen Vibrator über 100 ms von aus auf volle Amplitude bei 120 Hz hochfährt, diesen Zustand 200 ms lang beibehält und dann über 100 ms wieder herunterfährt:

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 angegebenen Werte für Frequenz und Amplitude nicht, fügt aber einen Startpunkt mit der Amplitude 0 hinzu, um einen reibungslosen Übergang zu gewährleisten.

Entwickler sind dafür verantwortlich, dass die in ihren PWLE-Effekten angegebene Häufigkeit innerhalb des vom Gerät unterstützten Bereichs liegt, wie im FOAM des Geräts definiert. Wenn die Werte diese Grenzwerte überschreiten, vibriert das Gerät nicht.

Frequency to Output Acceleration Mapping (FOAM)

Eine genaue Darstellung der Gerätefrequenz für die Ausgabe von Beschleunigungsfunktionen 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 Frequenz für die Ausgabe einer Beschleunigungskarte (Frequency of Output Acceleration Map, FOAM) bereitstellen. Das FOAM ist eine Datenstruktur, die vom HAL generiert wird und die Vibrationsfrequenz (in Hertz) der maximal erreichbaren Ausgabebeschleunigung (in G-Spitze) des Aktuators bei dieser Frequenz zuordnet. Diese Karte ist entscheidend, um zu verstehen, wie die Vibrationsausgabe für den unterstützten Frequenzbereich variiert, und um die grundlegende PWLE-API zu definieren.

Das folgende Diagramm zeigt ein Beispiel für ein 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 ein FOAM für einen typischen Resonanzaktuator.

Der FOAM dient drei Hauptzwecken:

• Vollständigen Frequenzbereich definieren:Der FOAM definiert den vollständigen Frequenzbereich des Geräts, indem die unterstützten minimalen und maximalen Vibrationsfrequenzen angegeben werden.
• Intensitäts- und Schärfewerte definieren:Die grundlegende PWLE-API arbeitet mit einer Skala für die menschliche Wahrnehmung von Intensität und Schärfe, die dann mithilfe der Beschleunigungswerte in der FOAM auf Hardwarefrequenz- und ‑amplitudenparameter abgebildet werden. Diese Zuordnung trägt dazu bei, dass die haptischen Effekte entsprechend den Hardwarefunktionen gerendert werden. Der Schärfebereich wird durch die Mindestwahrnehmungsschwelle 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 anhand der angestrebten Beschleunigung des Ausgangssignals bei der ausgewählten Frequenz der Amplitude zu. So wird sichergestellt, dass das ausgewählte Intensitätsniveau erreicht wird, ohne die Möglichkeiten des Geräts zu überschreiten.
• Offenlegung von Hardwarefunktionen:Das FOAM wird Entwicklern in VibratorFrequencyProfile zur Verfügung gestellt und bietet die vollständige Frequenz für die Ausgabe von Beschleunigungsdaten, die einige der haptischen Funktionen des Geräts beschreiben. Mit diesen Daten können Entwickler, die die erweiterte PWLE API verwenden, benutzerdefinierte Vibrationseffekte erstellen, die über die vom Framework definierten grundlegenden Intensitäts- und Schärfebereiche hinausgehen.

FOAM und einfache PWLE API

Das FOAM spielt eine wichtige Rolle bei der Gestaltung von Vibrationseffekten. Er wird verwendet, um den Schärfebereich für die Basic Envelope API zu berechnen und dafür zu sorgen, dass Vibrationen für den Nutzer wahrnehmbar sind. Dieser Bereich entspricht Frequenzen, bei denen die Ausgabebeschleunigung für jede Frequenz mindestens 10 dB über der Wahrnehmungsschwelle des Menschen (d. h. dem minimal wahrnehmbaren Pegel) liegt. Dadurch wird sichergestellt, dass die Vibrationen stark genug sind, um wahrgenommen zu werden.

Außerdem werden die FOAM-Daten verwendet, um die in der einfachen 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 sind vorhanden, um sicherzustellen, dass Geräte, die Hüllkurveneffekte unterstützen, einen nicht leeren Frequenzbereich haben, der wahrnehmbare Vibrationen erzeugt. So wird sichergestellt, dass das Gerät Vibrationen mit ausreichender Intensität erzeugen kann, die Nutzer deutlich spüren.

FOAM und erweiterte PWLE API

FOAM wird Entwicklern von 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 Ausgabebeschleunigung:Die maximal erreichbare Ausgabebeschleunigung des Geräts (in G) ist über getMaxOutputAccelerationGs verfügbar.
• Zuordnung von Häufigkeit zu Ausgabebeschleunigung:getFrequenciesOutputAcceleration bietet die Zuordnung von Häufigkeit zu Ausgabebeschleunigung, wie sie im HAL implementiert ist.

Entwickler können diese Informationen verwenden, wenn sie mit der erweiterten PWLE-API Hüllkurveneffekte erstellen. Wenn Sie beispielsweise eine Ausgabebeschleunigung (in G) angeben, müssen Sie sie in Bezug auf die maximale Ausgabebeschleunigung des Geräts auf einen Wert im Bereich [0,0, 1,0] normalisieren.

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

Grenzwert für die Erkennung der menschlichen Wahrnehmung

Der Schwellenwert für die Erkennung durch den Menschen bezieht sich auf die Mindestbeschleunigung einer Vibration, die eine Person zuverlässig erkennen kann. Dieser Wert variiert je nach Vibrationsfrequenz.

Das folgende Diagramm zeigt die Erkennungsschwelle für die haptische Wahrnehmung des Menschen¹ in Bezug auf die Beschleunigung als Funktion der zeitlichen Frequenz:

Abbildung 2: Schwellenwert für die Erkennung der haptischen Wahrnehmung des Menschen.

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

Wahrgenommene Vibrationsstärke im Vergleich zur Vibrationsbeschleunigungsamplitude

Die menschliche Wahrnehmung der Vibrationsintensität (ein Wahrnehmungsmaß) nimmt nicht linear mit der Vibrationsamplitude (einem physikalischen Parameter) zu. 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 der Erkennungsschwelle bei derselben Frequenz definiert ist. Die Schwingungsbeschleunigungsamplitude (in G-Spitze) kann also so berechnet werden:

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

Dabei ist die Amplitude dB die Summe aus Schallpegel und Erkennungsschwelle (der Wert entlang der Ordinate im folgenden Diagramm) bei einer bestimmten Frequenz.

So wird durch die PWLE-API sichergestellt, dass sich die wahrgenommene Intensität zwischen aufeinanderfolgenden Paaren von Kontrollpunkten linear ändert.

Das folgende Diagramm zeigt die Schwingungsbeschleunigungspegel² bei 10, 20, 30, 40 und 50 dB SL sowie die Erkennungsschwelle für die haptische Wahrnehmung des Menschen (0 dB SL) als Funktion der zeitlichen Frequenz.

Abbildung 3: Vibrationsbeschleunigungsstufen.

Häufigkeit der Beschleunigungskurve für maximale Leistung bestimmen

In diesem Abschnitt finden Sie eine allgemeine Anleitung dazu, wie Sie die Kurve für die Frequenz bis zur maximalen Beschleunigung des Geräts abrufen, die Sie zum Generieren der FOAM-Daten verwenden.

Maximale Spannungskurve (V) ermitteln

V ist die maximale Spannung, die sicher an den Vibrator angelegt werden kann, wenn er im Betriebsfrequenzbereich arbeitet. So wird sichergestellt, dass der Vibrationsmotor innerhalb sicherer Grenzen arbeitet, um Schäden zu vermeiden und die Vibrationsausgabe zu maximieren.

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

Berechne die maximale Beschleunigung (M).

M ist die maximale Beschleunigung, die Sie mit verschiedenen Methoden berechnen können. In diesem Abschnitt wird eine Methode für Geräte mit linearen Resonanzaktoren (LRAs) beschrieben.

Bei dieser Methode wird die maximal angelegte Spannung bei einer bestimmten Frequenz in einen entsprechenden maximalen Beschleunigungswert umgerechnet, der in G-Spitze ausgedrückt wird.

Die für diese Umrechnung 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ächliche Spannung, die an den Haptik-Aktuator angelegt wird

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

Loc_coeff: Standortkoeffizient zum Umrechnen der Beschleunigung auf Modulebene in die Beschleunigung auf Smartphone-Ebene

Rsys: Elektrischer Widerstand der Spule des Vibrationsmotors

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

w: Kreisfrequenz (Radiant pro Sekunde) des Treibersignals, berechnet als:

\(w = 2 \pi f\)

Psys_abs: Amplitudenreaktion eines Systems mit Masse, Dämpfer und Feder zweiter Ordnung, berechnet als:

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

Wnsys: Eigenfrequenz des schwingenden Systems

Qsys: Gütefaktor des Schwingungssystems

Loc_coeff ist das Verhältnis der Beschleunigung, die auf Smartphone-Ebene gemessen wird, zur Beschleunigung, die auf Modulebene gemessen wird. Dieses Verhältnis wird verwendet, um Beschleunigungsmessungen auf Modulebene in entsprechende Beschleunigungsmessungen auf Smartphone-Ebene umzurechnen. Auf Smartphone-Ebene wird die Beschleunigung aufgrund der Winkelbeschleunigung der Modulbewegung verstärkt. Dieser Koeffizient berücksichtigt diesen Effekt. Der Wert wird folgendermaßen berechnet:

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

Wenn die Beschleunigung des Moduls beispielsweise 1 g und die Beschleunigung des Smartphones 2,5 g beträgt, dann ist Loc_coeff = 2,5. Das entspricht einer 2,5-fachen 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 umrechnen.

FOAM-Kurve generieren

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

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

FOAM-Daten verfügbar machen

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

Es gibt keine strengen Anforderungen an die Auflösung des FOAM. Wir empfehlen jedoch, Kurven mit einem maximalen Peak zu definieren. In der Basic Envelope API wird nur der erste Peak verwendet, um die Vibrationseffekte zuzuordnen. Um die Genauigkeit der linearen Interpolation bei der Bestimmung von Zwischenbeschleunigungswerten zu optimieren, empfehlen wir, eine hohe Frequenzauflösung um den Peak herum zu definieren. Verwenden Sie beispielsweise 1-Hz-Schritte im Bereich von +/- 10 Hz der Spitzenfrequenz.

Funktionen und Einschränkungen von Geräten

Damit Entwickler ihre PWLE-Effekte für Android 16 und höher optimieren und die Kompatibilität auf verschiedenen Geräten sicherstellen können, enthält Android HAL-APIs zum Abfragen der PWLE-Funktionen des Geräts. Diese Methoden liefern Informationen zu den Einschränkungen des Geräts, z. B. die minimale oder maximale Dauer von PWLE-Primitiven und die Anzahl der Primitiven, die in einer PWLE-Komposition zulässig sind.

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 Mindestdauer für ein beliebiges primitives PWLE in Millisekunden ab.
• getPwleV2PrimitiveDurationMaxMillis: Ruft die maximale Dauer ab, die für ein beliebiges PWLE-Primitiv zulässig ist, in Millisekunden.
• 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 erweiterten PWLE API.

Das Framework verwendet diese APIs auch, wenn es Effekte verarbeitet, die mit der Basic 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, damit er innerhalb der zulässigen Grenzen liegt. Bei diesem Anpassungsprozess wird versucht, die ursprüngliche Intention und das ursprüngliche Design so weit wie möglich beizubehalten.