Implémenter des effets d'enveloppe linéaire par morceaux

Les effets d'enveloppe linéaire par morceaux (PWLE) sont des séquences de points définissant la fréquence et l'accélération des vibrations au fil du temps. Les PWLE offrent un retour haptique plus riche et plus dynamique.

Android 16 et versions ultérieures fournissent deux API pour les développeurs d'applications afin de créer des effets PWLE :

• API PWLE de base : simple, mais avec des limites. Parfait pour commencer rapidement. Il est disponible sur BasicEnvelopeBuilder.
• API PWLE avancée : offre plus de contrôle et de flexibilité, mais nécessite des connaissances en haptique et une certaine familiarité avec le matériel. Disponible sur WaveformEnvelopeBuilder.

Pour prendre en charge ces API, les appareils doivent implémenter les API HAL suivantes :

• FOAM (Frequency to output acceleration mapping) : fournit un mappage de la fréquence de vibration à l'accélération de sortie maximale possible pour l'appareil.
• Compose PWLE : lit une vibration définie par une PWLE de la forme d'onde de la vibration.

API PWLE de base

Pour créer rapidement des effets PWLE sans se plonger dans le matériel ni dans les nuances de la perception humaine, les développeurs peuvent utiliser l'API PWLE de base, définie à l'aide des paramètres suivants :

• La valeur Intensity (Intensité) comprise entre 0 et 1 représente l'intensité perçue de la vibration. Par exemple, une valeur de 0,5 est perçue comme la moitié de l'intensité maximale globale que l'appareil peut atteindre.
• La valeur Netteté comprise entre 0 et 1 représente la précision de la vibration. Les valeurs faibles correspondent à des vibrations plus douces, tandis que les valeurs élevées créent une sensation plus vive.
• Duration correspond au temps nécessaire pour passer du dernier point PWLE (c'est-à-dire la paire intensité et netteté) au nouveau, en millisecondes.

Voici un exemple de forme d'onde qui augmente l'intensité d'une vibration de faible à forte intensité maximale sur 500 ms, puis diminue jusqu'à 0 (désactivée) sur 100 ms :

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

Contraintes

Pour créer une expérience haptique fluide et homogène, les effets PWLE doivent commencer et se terminer avec une intensité de 0,0. L'API applique cette règle en fixant l'intensité de début à 0 et en générant une exception si l'intensité de fin n'est pas égale à 0. Cette contrainte empêche les effets dynamiques indésirables dans les vibrations en raison des discontinuités dans l'amplitude, qui peuvent avoir un impact négatif sur la perception haptique de l'utilisateur.

Pour garantir un rendu cohérent des effets PWLE dans l'écosystème Android, le framework exige que les appareils compatibles avec cette fonctionnalité puissent gérer une durée minimale de 10 ms entre les points PWLE et au moins 16 points pour les effets PWLE. Ces exigences sont appliquées par les tests VTS, ce qui permet de garantir des effets PWLE fiables sur les appareils Android.

API PWLE avancée

Les développeurs ayant des connaissances avancées en haptique peuvent définir des effets PWLE à l'aide des critères suivants :

• La valeur Amplitude dans la plage [0, 1] représente l'intensité réalisable à une fréquence donnée, telle que déterminée par le FOAM de l'appareil. Par exemple, une valeur de 0,5 génère la moitié de l'accélération de sortie maximale pouvant être atteinte à la fréquence donnée.
• La fréquence est spécifiée directement en Hertz.
• Duration correspond au temps nécessaire pour passer du dernier point PWLE au nouveau, en millisecondes.

Voici un exemple de forme d'onde qui fait passer un vibreur de l'état éteint à l'amplitude maximale à 120 Hz sur 100 ms, maintient cet état pendant 200 ms, puis redescend sur 100 ms :

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

Contraintes

Le framework ne modifie pas les valeurs de fréquence et d'amplitude demandées par le développeur, mais ajoute un point de départ d'amplitude 0 pour assurer une transition fluide.

Il incombe aux développeurs de s'assurer que la fréquence spécifiée dans leurs effets PWLE se situe dans la plage acceptée par l'appareil, telle que définie par le FOAM de l'appareil. Si les valeurs dépassent ces limites, l'appareil n'émet aucune vibration.

Mappage de la fréquence à l'accélération de sortie (FOAM)

Il est essentiel de représenter précisément la fréquence à laquelle un appareil peut générer des données d'accélération pour prendre en charge les API PWLE. Cette section explique l'importance de ces données, la façon dont les API PWLE les utilisent et le processus de génération.

Comprendre le mappage

Les appareils compatibles avec les effets PWLE doivent fournir une fréquence pour générer une carte d'accélération (FOAM). La FOAM est une structure de données générée par la HAL qui mappe la fréquence de vibration (en Hertz) à l'accélération de sortie maximale que l'actionneur peut atteindre (en G crête) à cette fréquence. Cette carte est essentielle pour comprendre comment la sortie de vibration varie pour la plage de fréquences acceptée et pour définir l'API PWLE de base.

Le graphique suivant montre un exemple de FOAM pour un actionneur résonant typique, avec une tension d'entrée limitée autour de la fréquence de résonance pour protéger le moteur :

Figure 1 : Exemple de FOAM pour un actionneur résonant typique.

Le FOAM remplit trois objectifs clés :

• Définition de la gamme de fréquences complète : le FOAM définit la gamme de fréquences complète de l'appareil en spécifiant les fréquences de vibration minimales et maximales prises en charge.
• Définir les valeurs d'intensité et de netteté : l'API PWLE de base fonctionne sur une échelle de perception humaine pour l'intensité et la netteté, qui sont ensuite mappées aux paramètres de fréquence et d'amplitude du matériel à l'aide des valeurs d'accélération de sortie dans le FOAM. Ce mappage permet de s'assurer que les effets haptiques sont rendus en fonction des capacités matérielles. La plage de netteté est définie par le seuil de perception minimal et correspond aux fréquences auxquelles l'appareil peut produire des effets haptiques que les utilisateurs peuvent ressentir. Le framework mappe les valeurs d'intensité à l'amplitude en fonction de l'accélération de sortie cible à la fréquence sélectionnée. Cela permet de s'assurer que le niveau d'intensité sélectionné est atteint tout en restant dans les limites des capacités de l'appareil.
• Exposition des capacités matérielles : le FOAM est exposé aux développeurs dans VibratorFrequencyProfile, ce qui fournit l'ensemble de données d'accélération de fréquence détaillant certaines des capacités haptiques de l'appareil. Ces données permettent aux développeurs qui utilisent l'API PWLE avancée de créer des effets de vibration personnalisés qui vont au-delà des plages d'intensité et de netteté de base définies par le framework.

FOAM et API PWLE de base

Le FOAM joue un rôle essentiel dans la forme des effets de vibration. Elle est utilisée pour calculer la plage de netteté de l'API d'enveloppe de base, ce qui permet de s'assurer que les vibrations sont perceptibles par l'utilisateur. Cette plage correspond aux fréquences où l'accélération de sortie n'est pas inférieure à 10 dB au-dessus du seuil de détection de la perception humaine (c'est-à-dire le niveau minimal perceptible) pour chaque fréquence. Cela garantit que les vibrations sont suffisamment fortes pour être ressenties.

De plus, le framework utilise les données FOAM pour mapper les valeurs d'intensité et de netteté utilisées dans l'API PWLE de base à leurs valeurs d'amplitude et de fréquence correspondantes. Ce mappage permet de produire un retour haptique perceptible sur différents appareils.

Des tests VTS sont en place pour s'assurer que les appareils compatibles avec les effets d'enveloppe disposent d'une plage de fréquences non vide qui produit des vibrations perceptibles. Cela permet de s'assurer que l'appareil peut produire des vibrations d'une intensité suffisante pour être clairement ressenties par les utilisateurs.

FOAM et API PWLE avancée

FOAM est exposé aux développeurs par VibratorFrequencyProfile avec les informations suivantes :

• Plage de fréquences : les développeurs peuvent récupérer les fréquences minimales et maximales prises en charge par l'appareil, en hertz, à l'aide de getMinFrequencyHz et getMaxFrequencyHz, respectivement.
• Accélération de sortie maximale : l'accélération de sortie maximale (en G) que l'appareil peut atteindre est disponible via getMaxOutputAccelerationGs.
• Mappage de la fréquence à l'accélération de sortie : getFrequenciesOutputAcceleration fournit le mappage de la fréquence à l'accélération de sortie tel qu'il est implémenté dans la HAL.

Les développeurs peuvent utiliser ces informations lorsqu'ils créent des effets d'enveloppe avec l'API PWLE avancée. Par exemple, lorsqu'ils spécifient une accélération de sortie (en G), ils doivent la normaliser sur une valeur comprise dans la plage [0.0, 1.0], par rapport à l'accélération de sortie maximale de l'appareil.

Avec l'API PWLE avancée, les développeurs peuvent utiliser toute la gamme de fréquences. Il est donc essentiel que les données FOAM fournies soient sans danger pour le vibreur et ne dépassent pas ses capacités.

Seuil de détection de la perception humaine

Le seuil de détection de la perception humaine fait référence à l'accélération minimale d'une vibration qu'une personne peut détecter de manière fiable. Ce niveau varie en fonction de la fréquence des vibrations.

Le graphique suivant montre le seuil de détection de la perception haptique humaine¹, en accélération, en fonction de la fréquence temporelle :

Figure 2. Seuil de détection de la perception haptique humaine.

Pour que les utilisateurs puissent ressentir les effets haptiques de manière cohérente, les tests VTS valident que les appareils dotés de capacités d'enveloppe ont une plage de fréquences qui peut produire des amplitudes de vibration dépassant le seuil de détection de la perception humaine de 10 dB.

Intensité des vibrations perçues par rapport à l'amplitude de l'accélération des vibrations

La perception humaine de l'intensité des vibrations (une mesure de perception) ne croît pas de manière linéaire avec l'amplitude des vibrations (un paramètre physique). L'API PWLE suppose que lorsqu'un concepteur ou un développeur pense aux changements d'intensité des vibrations, il s'attend à ce que l'intensité perçue suive une PWLE. L'intensité perçue est caractérisée par le niveau de sensation (SL), qui est défini comme le nombre de dB au-dessus du seuil de détection à la même fréquence. L'amplitude d'accélération des vibrations (en G crête) peut donc être calculée comme suit :

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

L'amplitude en dB correspond à la somme du niveau de pression acoustique et du seuil de détection (la valeur le long de l'ordonnée dans le graphique suivant) à une fréquence donnée.

De cette façon, l'API PWLE garantit que l'intensité perçue change de manière linéaire entre les paires successives de points de contrôle.

Le graphique suivant montre les niveaux d'accélération des vibrations² à 10, 20, 30, 40 et 50 dB SL, ainsi que le seuil de détection de la perception haptique humaine (0 dB SL), en fonction de la fréquence temporelle.

Figure 3. Niveaux d'accélération des vibrations.

Déterminer la courbe d'accélération de la fréquence à la puissance maximale

Cette section fournit des consignes générales sur la façon d'obtenir la courbe d'accélération de la fréquence à la sortie maximale de l'appareil, que vous utilisez pour générer les données FOAM.

Obtenez la courbe de tension maximale (V).

V correspond à la tension maximale qui peut être appliquée au vibreur en toute sécurité sur sa plage de fréquences de fonctionnement. Cela garantit que le vibreur fonctionne dans des limites sûres, ce qui évite tout dommage et maximise la puissance des vibrations.

Si le matériel inclut une fonctionnalité de limitation de la tension, utilisez-la pour mesurer directement la tension maximale pouvant être atteinte dans la plage de fréquences acceptée.

Calculer l'accélération maximale (M)

M correspond à l'accélération maximale, que vous pouvez calculer à l'aide de différentes méthodologies. Cette section présente une méthode pour les appareils utilisant des actionneurs résonants linéaires (LRA).

Cette méthode convertit la tension maximale appliquée à une fréquence donnée en une valeur d'accélération maximale correspondante, exprimée en G crête.

L'équation de base utilisée pour cette conversion est la suivante :

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

Où :

Vsys : niveau de tension réel appliqué à l'actionneur haptique

BLsys : produit de l'intensité du champ magnétique (B) et de la longueur du conducteur (L) du moteur vibrant

Loc_coeff : coefficient de localisation permettant de convertir l'accélération au niveau du module en accélération au niveau du téléphone

Rsys : résistance électrique de la bobine du moteur vibrant

MPhone : masse de l'appareil (par exemple, un téléphone)

w : fréquence angulaire (radians par seconde) du signal d'entraînement, calculée comme suit :

\(w = 2 \pi f\)

Psys_abs : réponse d'amplitude d'un système de masse, d'amortisseur et de ressort de second ordre, calculée comme suit :

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

Wnsys : fréquence naturelle du système de vibration

Qsys : facteur de qualité du système vibrant

Loc_coeff correspond au rapport entre l'accélération mesurée au niveau du téléphone et celle mesurée au niveau du module. Ce ratio est utilisé pour convertir les lectures d'accélération au niveau du module en lectures d'accélération équivalentes au niveau du téléphone. Au niveau du téléphone, en raison de l'accélération angulaire du mouvement du module, l'accélération est amplifiée. Ce coefficient tient compte de ce type d'effet. Elle est calculée de la manière suivante :

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

Par exemple, si l'accélération du module est de 1 g et celle du téléphone de 2,5 g, alors Loc_coeff = 2,5. Cela indique une amplification de 2,5x.

Le framework Android prend en compte la fréquence en hertz. Le HAL doit donc convertir l'unité de fréquence de radians par seconde en hertz lors de la génération des données FOAM.

Générer la courbe FOAM

Combinez la courbe de tension maximale (V) et le calcul de l'accélération (M) pour déterminer la courbe FOAM :

• Pour chaque fréquence (f) de la plage souhaitée, recherchez la tension maximale correspondante V(f) à partir de votre courbe de tension maximale.
• Calculez l'accélération maximale à cette fréquence à l'aide de l'équation ci-dessus, en remplaçant Vsys par V(f) et w par f. Vous bénéficiez ainsi de M(V(f), f).
• Cette accélération calculée correspond à votre valeur FOAM(f).

Exposer les données FOAM

Une fois la courbe FOAM générée, le HAL la représente sous la forme d'une liste d'objets FrequencyAccelerationMapEntry. Chaque entrée définit un point dans le mappage, en spécifiant une fréquence (en Hertz) et son accélération de sortie maximale correspondante (en G crête).

Bien qu'il n'y ait pas d'exigences strictes concernant la résolution de la FOAM, nous vous recommandons de définir des courbes avec un seul pic maximal. Seule la première crête est utilisée dans l'API d'enveloppe de base pour mapper les effets de vibration. Pour optimiser la précision de l'interpolation linéaire lors de la détermination des valeurs d'accélération intermédiaires, nous vous recommandons de définir une résolution de fréquence élevée autour du pic. Par exemple, utilisez des incréments de 1 Hz dans la plage de +/- 10 Hz de la fréquence maximale.

Fonctionnalités et limites des appareils

Pour Android 16 et versions ultérieures, afin d'aider les développeurs à optimiser leurs effets PWLE et à assurer la compatibilité entre les appareils, Android inclut des API HAL pour interroger les capacités PWLE de l'appareil. Ces méthodes fournissent des informations sur les limites de l'appareil, telles que la durée minimale ou maximale de la primitive PWLE et le nombre de primitives autorisées dans une composition PWLE.

Les API HAL incluent les éléments suivants :

• CAP_COMPOSE_PWLE_EFFECTS_V2 : renvoyé par IVibrator.getCapabilities lorsque l'appareil est compatible avec cette fonctionnalité.
• getFrequencyToOutputAccelerationMap : récupère les données FOAM.
• getPwleV2PrimitiveDurationMinMillis : récupère la durée minimale autorisée pour toute PWLE primitive en millisecondes.
• getPwleV2PrimitiveDurationMaxMillis : récupère la durée maximale autorisée pour toute PWLE primitive en millisecondes.
• getPwleV2CompositionSizeMax : récupère le nombre maximal de primitives PWLE prises en charge par IVibrator.composePwleV2.

Ces informations sont exposées aux développeurs pour leur permettre d'adapter leurs effets aux capacités spécifiques de l'appareil cible, en particulier lorsqu'ils utilisent l'API PWLE avancée.

Le framework utilise également ces API lors de la gestion des effets créés avec l'API de base. Si un effet dépasse les limites de l'appareil (par exemple, trop de points PWLE ou une durée supérieure à la durée maximale), le framework ajuste automatiquement l'effet pour qu'il respecte les limites autorisées. Ce processus d'ajustement tente de préserver autant que possible l'intention et l'esprit du design d'origine.