Implementieren Sie stückweise lineare Envelope-Effekte.

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

Android 16 und höher bietet zwei APIs für App-Entwickler, mit denen sich PWLE-Effekte erstellen lassen:

• Grundlegende PWLE API:Einfach, aber mit Einschränkungen. Gut für den schnellen Einstieg. Sie finden sie unter BasicEnvelopeBuilder.
• Erweiterte PWLE API:Bietet mehr Kontrolle und Flexibilität. Erfordert Kenntnisse über Haptik und einige Kenntnisse über Hardware. Verfügbar unter WaveformEnvelopeBuilder.

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

• Zuordnung der Frequenz zur Ausgabebeschleunigung (FOAM): Hier wird die Vibrationsfrequenz der maximal erreichbaren Ausgabebeschleunigung des Geräts zugeordnet.
• PWLE erstellen:Hiermit wird eine Vibration abgespielt, die durch eine PWLE der Vibrationswellenform definiert ist.

Einfache PWLE API

Wenn Entwickler schnell PWLE-Effekte erstellen möchten, ohne sich mit der Hardware oder den Feinheiten der menschlichen Wahrnehmung befassen zu müssen, können sie die grundlegende PWLE API verwenden, die mit den folgenden Parametern definiert ist:

• Der Wert Intensität im Bereich [0, 1] gibt die wahrgenommene Stärke der Vibration an. 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 [0, 1] gibt die Schärfe der Vibration an. Je niedriger der Wert, desto weicher sind die Vibrationen. Höhere Werte sorgen für ein schärferes Gefühl.
• Dauer ist die Zeit in Millisekunden, die für den Übergang vom letzten PWLE-Punkt (d. h. dem Paar aus Intensität und Schärfe) zum neuen benötigt wird.

Hier ist eine Beispielwellenform, 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) abnimmt:

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

Einschränkungen

Für eine reibungslose und nahtlose haptische Erfahrung müssen PWLE-Effekte mit einer Intensität von 0, 0 beginnen und enden. Die API erzwingt dies, indem die Startintensität auf 0 festgelegt wird und eine Ausnahme ausgelöst wird, wenn die Endintensität nicht 0 ist. Diese Einschränkung verhindert unerwünschte dynamische Effekte bei den Vibrationen aufgrund von Brüchen in der Amplitude, die sich negativ auf die haptische Wahrnehmung des Nutzers auswirken können.

Um ein einheitliches PWLE-Effekt-Rendering im gesamten Android-System zu ermöglichen, müssen Geräte, die diese Funktion unterstützen, eine Mindestdauer von 10 ms zwischen den PWLE-Punkten und mindestens 16 Punkte 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.

Erweiterte PWLE API

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

• Der Wert Amplitude im Bereich [0, 1] entspricht der erreichbaren Stärke bei einer bestimmten Frequenz, wie vom FOAM des Geräts bestimmt. Bei einem Wert von 0,5 wird beispielsweise die Hälfte der maximalen Ausgabebeschleunigung generiert, die bei der angegebenen Frequenz erreicht werden kann.
• Die Frequenz wird direkt in Hertz angegeben.
• Dauer ist die Zeit in Millisekunden, die für den Übergang vom letzten Punkt mit niedrigerem Wert zum neuen Punkt benötigt wird.

Hier sehen Sie eine Beispielwellenform, bei der ein Vibrator innerhalb von 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 angeforderten Frequenz- und Amplitudenwerte nicht, sondern fügt einen Ausgangspunkt mit einer Amplitude von 0 hinzu, um einen reibungslosen Übergang zu ermöglichen.

Entwickler müssen dafür sorgen, dass die in ihren PWLE-Effekten angegebene Frequenz in den unterstützten Bereich des Geräts fällt, wie vom FOAM des Geräts definiert. Wenn die Werte diese Limits überschreiten, vibriert das Gerät nicht.

Zuordnung von Häufigkeit zu Ausgabebeschleunigung (Frequency to Output Acceleration Mapping, FOAM)

Eine genaue Darstellung der Taktfrequenz eines Geräts und seiner Beschleunigungsfunktionen ist für die Unterstützung der PWLE APIs unerlässlich. In diesem Abschnitt wird die Bedeutung dieser Daten, ihre Verwendung in PWLE APIs und die Generierung beschrieben.

Zuordnung

Geräte, die PWLE-Effekte unterstützen, müssen eine Frequenz für die Ausgabe der Beschleunigungskarte (FOAM) angeben. Die FOAM ist eine vom HAL generierte Datenstruktur, die die Vibrationsfrequenz (in Hertz) der maximal erreichbaren Ausgangsbeschleunigung (in G-Peak) des Aktors bei dieser Frequenz zuordnet. Diese Karte ist entscheidend, um zu verstehen, wie sich die Vibrationsleistung im unterstützten Frequenzbereich ändert, und um die grundlegende PWLE API zu definieren.

Die folgende Abbildung zeigt ein Beispiel für ein FOAM für einen typischen ResonanzAktor, bei dem die Eingangsspannung zum Schutz des Motors auf die Resonanzfrequenz begrenzt ist:

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

Der FOAM dient drei Hauptzwecken:

• Vollständigen Frequenzbereich definieren:Der FOAM definiert den vollen Frequenzbereich des Geräts, indem die unterstützten minimalen und maximalen Vibrationsfrequenzen angegeben werden.
• Intensität und Schärfe definieren:Die grundlegende PWLE API verwendet eine Skala für die menschliche Wahrnehmung von Intensität und Schärfe, die dann mithilfe der Ausgabebeschleunigungswerte im FOAM in Hardwarefrequenz- und Amplitudenparameter umgewandelt werden. Durch diese Zuordnung wird sichergestellt, dass die haptischen Effekte gemäß den Hardwarefunktionen gerendert werden. Der Schärfebereich wird durch den minimalen wahrnehmbaren Grenzwert 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 der Amplitude zu, basierend auf der Zielausgabebeschleunigung bei der ausgewählten Frequenz. So wird sichergestellt, dass das ausgewählte Intensitätsniveau erreicht wird, ohne die Möglichkeiten des Geräts zu überschreiten.
• Hardwarefunktionen freigeben:Der FOAM wird Entwicklern in VibratorFrequencyProfile zur Verfügung gestellt. Er enthält den vollständigen Datensatz mit Frequenz und Ausgabebeschleunigung, der einige der haptischen Funktionen des Geräts beschreibt. Anhand dieser Daten können Entwickler mit der erweiterten PWLE API benutzerdefinierte Vibrationseffekte erstellen, die über die vom Framework definierten grundlegenden Intensitäts- und Schärfebereiche hinausgehen.

FOAM und grundlegende PWLE API

Die FOAM spielt eine wichtige Rolle bei der Gestaltung von Vibrationseffekten. Mit diesem Wert wird der Schärfebereich für die grundlegende Envelope API berechnet, damit Vibrationen für den Nutzer wahrnehmbar sind. Dieser Bereich entspricht Frequenzen, bei denen die Ausgabebeschleunigung für jede Frequenz mindestens 10 dB über dem Wahrnehmungsgrenzwert des Menschen liegt (d. h. dem Mindestwahrnehmungspegel). So sind die Vibrationen stark genug, um wahrgenommen zu werden.

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

VTS-Tests sollen dafür sorgen, dass Geräte, die Hüllkurveneffekte unterstützen, einen nicht leeren Frequenzbereich haben, der wahrnehmbare Vibrationen erzeugt. So kann das Gerät Vibrationen mit ausreichender Intensität erzeugen, die von den Nutzern deutlich wahrgenommen werden.

FOAM und erweiterte PWLE API

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

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

Entwickler können diese Informationen beim Erstellen von Envelope-Effekten mit der erweiterten PWLE API verwenden. Wenn beispielsweise eine Ausgabebeschleunigung (in G) angegeben wird, muss sie auf einen Wert im Bereich [0,0; 1, 0] normalisiert werden, bezogen auf die maximale Ausgabebeschleunigung des Geräts.

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 durch Menschen

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

Die folgende Abbildung zeigt den Wahrnehmungsgrenzwert für die haptische Wahrnehmung des Menschen¹ in Beschleunigung als Funktion der zeitlichen Frequenz:

Abbildung 2: Der Schwellenwert für die haptische Wahrnehmung von Menschen.

Damit Nutzer die haptischen Effekte immer spüren können, wird bei VTS-Tests geprüft, ob Geräte mit Hüllkurvenfunktionen einen Frequenzbereich haben, der Vibrationsamplituden erzeugen kann, die den Wahrnehmungsgrenzwert des Menschen um 10 dB überschreiten.

Empfundene Vibrationsintensität im Vergleich zur Amplitude der Vibrationsbeschleunigung

Die menschliche Wahrnehmung der Vibrationsintensität (ein Wahrnehmungsmaß) steigt nicht linear mit der Vibrationsamplitude (ein physikalischer Parameter). Die PWLE API geht davon aus, dass Designer oder Entwickler, wenn sie über Änderungen der Vibrationsstärke nachdenken, davon ausgehen, dass die wahrgenommene Intensität einer PWLE folgt. Die wahrgenommene Intensität wird durch das Sensation Level (SL) charakterisiert, das als Dezibel über dem Erkennungsgrenzwert bei derselben Frequenz definiert ist. Die Vibrationsbeschleunigungsamplitude (in g-Peak) kann daher so berechnet werden:

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

Dabei ist die Amplitude in dB die Summe aus SL und dem Erkennungsgrenzwert (der Wert entlang der Ordinate in der folgenden Abbildung) bei einer bestimmten Frequenz.

So sorgt die PWLE API dafür, dass sich die wahrgenommene Intensität zwischen aufeinanderfolgenden Paaren von Kontrollpunkten linear ändert.

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

Abbildung 3: Vibrationsbeschleunigungsstufen

Beschleunigungskurve für die Frequenz bis zur maximalen Leistung bestimmen

In diesem Abschnitt finden Sie allgemeine Hinweise dazu, wie Sie die Kurve für die Frequenz bis zur maximalen Ausgabebeschleunigung vom Gerät abrufen, die Sie zum Generieren der FOAM-Daten verwenden.

Maximalspannungskurve (V) abrufen

V ist die maximale Spannung, die dem Vibrator im gesamten Betriebsfrequenzbereich sicher zugeführt werden kann. So wird sichergestellt, dass der Vibrator innerhalb sicherer Grenzen arbeitet, was Schäden verhindert und die Vibrationsleistung maximiert.

Wenn die Hardware eine Spannungsbegrenzungsfunktion hat, können Sie damit die maximal erreichbare Spannung im unterstützten Frequenzbereich direkt messen.

Maximale Beschleunigung (M) berechnen

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) gezeigt.

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

Für diese Umwandlung wird die folgende Grundgleichung verwendet:

\(\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: Die tatsächliche Spannungsstufe, die auf den haptischen Aktor 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 Smartphone-Ebene

Rsys: Elektrischer Widerstand der Spule des Vibrationsmotors

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

w: Winkelfrequenz (Radiane pro Sekunde) des antreibenden Signals, berechnet nach:

\(w = 2 \pi f\)

Psys_abs: Amplitudengang eines Masse-Dämpfer-Feder-Systems 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 schwingenden Systems

Loc_coeff ist das Verhältnis der auf Smartphone-Ebene gemessenen Beschleunigung zur auf Modulebene gemessenen Beschleunigung. Mit diesem Verhältnis werden Beschleunigungsmessungen auf Modulebene in entsprechende Beschleunigungsmessungen auf Smartphone-Ebene umgewandelt. Auf Smartphone-Ebene wird die Beschleunigung aufgrund der Winkelbeschleunigung der Modulbewegung verstärkt. Dieser Koeffizient berücksichtigt diesen Effekt. Die Berechnung erfolgt so:

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

Wenn die Modulbeschleunigung beispielsweise 1 g und die Smartphone-Beschleunigung 2,5 g beträgt, 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 Radian 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) in der Kurve für die maximale Spannung.
• Berechnen Sie die maximale Beschleunigung bei dieser Frequenz anhand der obigen Gleichung, indem Sie V(f) anstelle von Vsys und die entsprechende f anstelle von w einsetzen. Sie erhalten dann M(V(f), f).
• Diese berechnete Beschleunigung ist Ihr FOAM(f)-Wert.

FOAM-Daten freigeben

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

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

Gerätefunktionen und -einschränkungen

Unter Android 16 und höher enthält Android HAL-APIs zum Abfragen der PWLE-Funktionen des Geräts, damit Entwickler ihre PWLE-Effekte optimieren und die geräteübergreifende Kompatibilität gewährleisten können. Diese Methoden liefern Informationen zu den Einschränkungen des Geräts, z. B. zur Mindest- oder Maximaldauer von PWLE-Primitiven und zur Anzahl der in einer PWLE-Komposition zulässigen Primitiven.

Zu den HAL-APIs gehören:

• 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 jede primitive PWLE in Millisekunden ab.
• getPwleV2PrimitiveDurationMaxMillis: Ruft die maximal zulässige Dauer für jede primitive PWLE in Millisekunden ab.
• getPwleV2CompositionSizeMax: Ruft die maximale Anzahl von PWLE-Primitiven ab, die von IVibrator.composePwleV2 unterstützt werden.

Diese Informationen sind für Entwickler verfügbar, 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 beim Umgang mit Effekten, die mit der Basis-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 so an, dass er innerhalb der zulässigen Grenzen liegt. Bei diesem Anpassungsprozess wird versucht, die ursprüngliche Absicht und das ursprüngliche Erscheinungsbild des Designs so weit wie möglich beizubehalten.