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

Les effets d'enveloppe linéaire par morceaux (PWLE, piecewise linear envelope) sont des séquences de points qui définissent 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 pour créer des effets PWLE:

• API PWLE de base:simple, mais avec des limites. Parfait pour commencer rapidement. Vous pouvez y accéder à l'adresse BasicEnvelopeBuilder.
• API PWLE avancée:offre plus de contrôle et de flexibilité. 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:

• Mappage de la fréquence à l'accélération de sortie (FOAM) : fournit un mappage de la fréquence de vibration à l'accélération de sortie maximale possible pour l'appareil.
• Compose PWLE (Composer une PWLE) : lit une vibration définie par une PWLE de la forme d'onde de 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 de ces paramètres:

• La valeur Intensité comprise dans la plage [0, 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 dans la plage [0, 1] représente la netteté de la vibration. Des valeurs plus faibles correspondent à des vibrations plus fluides, tandis que des valeurs plus élevées créent une sensation plus nette.
• Durée : temps nécessaire pour passer du dernier point PWLE (c'est-à-dire la paire d'intensité et de netteté) au nouveau, en millisecondes.

Voici un exemple de forme d'onde qui augmente l'intensité d'une tonalité basse à une tonalité haute de vibration maximale sur 500 ms, puis diminue à 0 (arrêt) 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 fluide, 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 génère une exception si l'intensité de fin n'est pas égale à 0. Cette contrainte évite les effets dynamiques indésirables dans les vibrations en raison de discontinuités dans l'amplitude, qui peuvent avoir un impact négatif sur la perception haptique de l'utilisateur.

Pour garantir un rendu d'effet PWLE cohérent 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 des tests VTS, qui contribuent à garantir des effets PWLE fiables sur les appareils Android.

API Advanced PWLE

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 comprise dans la plage [0, 1] représente l'intensité atteignable à 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 obtenue à la fréquence donnée.
• La fréquence est spécifiée directement en Hertz.
• Durée : 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 "arrêt" à l'amplitude maximale à 120 Hz sur 100 ms, maintient cet état pendant 200 ms, puis diminue progressivement 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 fournies par le développeur, mais ajoute un point de départ d'amplitude 0 pour assurer une transition fluide.

Les développeurs doivent s'assurer que la fréquence spécifiée dans leurs effets PWLE se situe dans la plage compatible de l'appareil, comme défini par le FOAM de l'appareil. Si les valeurs dépassent ces limites, l'appareil n'émet pas de vibration.

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

Une représentation précise des capacités de fréquence à l'accélération de sortie d'un appareil est essentielle pour prendre en charge les API PWLE. Cette section détaille l'importance de ces données, la façon dont elles sont utilisées par les API PWLE et le processus de génération.

Comprendre le mappage

Les appareils compatibles avec les effets PWLE doivent fournir une carte d'accélération de sortie (FOAM, Frequency to Output Acceleration Map). La FOAM est une structure de données générée par le HAL qui met en correspondance la fréquence de vibration (en Hertz) avec l'accélération de sortie maximale réalisable de l'actionneur (en G peak) à cette fréquence. Cette carte est essentielle pour comprendre comment la sortie de vibration varie pour la plage de fréquences prise en charge 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 fonctions principales:

• Définition de la plage de fréquences complète:la FOAM définit la plage de fréquences complète de l'appareil en spécifiant les fréquences de vibration minimales et maximales compatibles.
• Définition des 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 sur les paramètres de fréquence et d'amplitude matériels à l'aide des valeurs d'accélération de sortie dans le FOAM. Cette mise en correspondance permet de s'assurer que les effets haptiques sont affichés en fonction des fonctionnalités matérielles. La plage de netteté est définie par le seuil minimal de perception et correspond aux fréquences où 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 fonctionnalités matérielles:le FOAM est exposé aux développeurs dans VibratorFrequencyProfile, fournissant l'ensemble de données complet de fréquence à l'accélération de sortie détaillant certaines des fonctionnalité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

La mousse joue un rôle essentiel dans la formation des effets de vibration. Il permet de calculer la plage de netteté pour l'API d'enveloppe de base, ce qui garantit que les vibrations sont perceptibles par l'utilisateur. Cette plage correspond aux fréquences où l'accélération de sortie est supérieure ou égale à 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 sur leurs valeurs d'amplitude et de fréquence correspondantes. Ce mappage permet de produire un retour haptique perceptible sur différents appareils.

Les tests VTS sont mis 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 de getMaxFrequencyHz, respectivement.
• Accélération de sortie maximale:l'accélération de sortie maximale (en G) de l'appareil est disponible via getMaxOutputAccelerationGs.
• Mappage de la fréquence sur l'accélération de sortie:getFrequenciesOutputAcceleration fournit le mappage de la fréquence sur l'accélération de sortie tel qu'implémenté dans le HAL.

Les développeurs peuvent utiliser ces informations lors de la création d'effets d'enveloppe avec l'API PWLE avancée. Par exemple, lorsqu'il spécifie une accélération de sortie (en G), il doit la normaliser à 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 plage 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 de vibration.

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 de manière cohérente les effets haptiques, les tests VTS valident que les appareils dotés de fonctionnalités d'enveloppe ont une plage de fréquences pouvant produire des amplitudes de vibration supérieures au seuil de détection de la perception humaine de 10 dB.

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

La perception humaine de l'intensité des vibrations (une mesure de la perception) n'augmente pas de manière linéaire avec l'amplitude des vibrations (un paramètre physique). L'API PWLE suppose qu'un concepteur ou un développeur qui réfléchit aux variations de l'intensité des vibrations 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 en dB au-dessus du seuil de détection à la même fréquence. Par conséquent, l'amplitude d'accélération des vibrations (en pic G) peut être calculée comme suit:

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

Où le dB d'amplitude correspond à la somme de la SL et du seuil de détection (valeur le long de l'ordonnée dans le graphique suivant) à une fréquence donnée.

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

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 sortie maximale

Cette section fournit des conseils généraux pour obtenir la courbe de fréquence à l'accélération de sortie maximale de l'appareil, que vous utiliserez pour générer les données FOAM.

Obtenir la courbe de tension maximale (V)

V correspond à la tension maximale pouvant être appliquée de manière sécurisée au vibreur sur sa plage de fréquences de fonctionnement. Cela garantit que le vibreur fonctionne dans des limites de sécurité, ce qui évite tout dommage et maximise la sortie de vibration.

Si le matériel inclut une fonctionnalité de limitation de la tension, utilisez-la pour mesurer directement la tension maximale réalisable dans la plage de fréquences prise en charge.

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

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

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

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 position 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 (téléphone, par exemple)

w: fréquence angulaire (radians par seconde) du signal de commande, calculée comme suit:

\(w = 2 \pi f\)

Psys_abs: réponse en 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 vibrant

Qsys: facteur de qualité du système vibrant

Loc_coeff est le rapport entre l'accélération mesurée au niveau du téléphone et l'accélération mesurée au niveau du module. Ce ratio permet de convertir les mesures d'accélération au niveau du module en mesures 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, et 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,5 fois.

Le framework Android utilise la fréquence en hertz. Le HAL doit donc convertir l'unité de fréquence des 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 V(f) correspondante à 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 le f correspondant par w. Vous obtenez ainsi 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 de la mise en correspondance, en spécifiant une fréquence (en Hertz) et son accélération de sortie maximale correspondante (en G peak).

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 pic maximal. Seul le premier pic est utilisé dans l'API d'enveloppe de base pour cartographier 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 haute fréquence autour du pic. Par exemple, utilisez des incréments de 1 Hz dans la plage de +/- 10 Hz de la fréquence de pointe.

Fonctionnalités et limites des appareils

Pour Android 16 et versions ultérieures, Android inclut des API HAL pour interroger les fonctionnalités PWLE de l'appareil afin d'aider les développeurs à optimiser leurs effets PWLE et à assurer la compatibilité entre les appareils. Ces méthodes fournissent des informations sur les limites de l'appareil, telles que la durée minimale ou maximale des primitives 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 primitive PWLE en millisecondes.
• getPwleV2PrimitiveDurationMaxMillis: récupère la durée maximale autorisée pour toute primitive PWLE en millisecondes.
• getPwleV2CompositionSizeMax: récupère le nombre maximal de primitives PWLE compatibles avec IVibrator.composePwleV2.

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

Le framework utilise également ces API pour gérer les 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 dépassant 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'ambiance d'origine de la conception.