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 les aider à créer des effets PWLE :

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

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

• Fréquence de résonance : fournit la fréquence de résonance de l'actionneur.
• 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 réalisable pour l'appareil.
• Composer un PWLE : lit une vibration définie par un PWLE de la forme d'onde de vibration.

Remarque : Clarification de la terminologie : cette page utilise l'amplitude et la fréquence pour les mesures physiques, et l'intensité et la netteté pour les paramètres perceptuels.

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 de l'intensité comprise entre 0 et 1 représente la force perçue de la vibration. Par exemple, une valeur de 0,5 est perçue comme la moitié de l'intensité maximale globale pouvant être atteinte par l'appareil.
• La valeur de la netteté comprise entre 0 et 1 représente la netteté de la vibration. Les valeurs inférieures se traduisent par des vibrations plus douces, tandis que les valeurs supérieures créent une sensation plus nette.
• La durée correspond au temps nécessaire pour passer du dernier point PWLE (c'est-à-dire la paire intensité/netteté) au nouveau, en millisecondes.

Remarque : L’intensité perçue de la vibration ne correspond pas de manière linéaire à l’accélération de sortie de la vibration. Le framework Android traduit le paramètre d'enveloppe d'intensité en amplitude de vibration, en tenant compte de la loi de puissance régissant la relation entre l'intensité perçue de la vibration et l' amplitude d'accélération de la vibration. Cette amplitude traduite est ensuite envoyée à l'implémentation matérielle.

Voici un exemple de forme d'onde qui augmente l'intensité d'un son grave à un son aigu de force maximale sur 500 ms, puis diminue jusqu'à 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 transparente, les effets PWLE doivent commencer et se terminer par 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 empêche 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 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 20 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 de l'amplitude comprise entre 0 et 1 représente la force 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.
• La durée 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 vibrateur de l'état désactivé à 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 fournies par le développeur, mais ajoute un point de départ d'amplitude 0 pour assurer une transition fluide.

Les développeurs sont responsables de s'assurer que la fréquence spécifiée dans leurs effets PWLE se situe dans la plage compatible de l'appareil, telle que définie par le FOAM de l'appareil. Si les valeurs dépassent ces limites, l'appareil ne lit aucune vibration.

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

Une représentation précise des capacités de fréquence à accélération de sortie d'un appareil est essentielle pour la prise en charge des API PWLE. Cette section explique l'importance de ces données, comment 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 un mappage de la fréquence à l'accélération de sortie (FOAM). Le FOAM est une structure de données générée par le HAL qui mappe la fréquence de vibration (en Hertz) à l'accélération de sortie maximale réalisable de l'actionneur (en G crête) à cette fréquence. Ce mappage est essentiel pour comprendre comment la sortie de vibration varie pour la plage de fréquences compatible 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éfinir la plage de fréquences complète : le 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é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 matériels à 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 minimal perceptible 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.
• Exposer les capacités matérielles : le FOAM est exposé aux développeurs dans VibratorFrequencyProfile, fournissant l'ensemble complet de données de fréquence à accélération de sortie 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 conception des effets de vibration. Il est utilisé pour calculer la plage de netteté de l'API d'enveloppe de base, en veillant à ce que les vibrations soient perceptibles par l'utilisateur. Cette plage correspond aux fréquences à partir desquelles l'accélération de sortie atteint d'abord 10 dB au-dessus du seuil de détection de la perception humaine (c'est-à-dire le niveau minimal perceptible), jusqu'à ce que l'accélération de sortie soit la dernière au-dessus de ce seuil. Cette plage doit inclure la fréquence de résonance de l'actionneur.

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 ont une plage de fréquences non vide qui produit des vibrations perceptibles et que la plage contient la fréquence de résonance de l'actionneur. 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

Le 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 compatibles de l'appareil, en Hertz, à l'aide de getMinFrequencyHz et getMaxFrequencyHz, respectivement.
• Accélération de sortie maximale : l'accélération de sortie maximale réalisable de l'appareil (en G) 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'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'ils spécifient une accélération de sortie (en G), ils doivent la normaliser à une valeur comprise entre 0,0 et 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 l'ensemble de la plage de fréquences. Il est donc essentiel que les données FOAM fournies soient sécurisées pour le vibrateur 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 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 pouvant produire des amplitudes de vibration dépassant le seuil de détection de la perception humaine de 10 dB.

Intensité perçue de la vibration par rapport à l'amplitude d'accélération de la vibration

La perception humaine de l'intensité de la vibration (une mesure de la perception) ne croît pas de manière linéaire avec l'amplitude de la vibration (un paramètre physique). L'API PWLE suppose que lorsqu'un concepteur ou un développeur pense aux changements de force de vibration, il s'attend à ce que l'intensité perçue suive un 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. Ainsi, l'amplitude d'accélération de la vibration (en G crête) peut être calculée comme suit :

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

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

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 de la vibration² à 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 de la vibration.

Déterminer la courbe de fréquence à accélération de sortie maximale

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

Obtenir la courbe de tension maximale (V)

V est la tension maximale qui peut être appliquée en toute sécurité au vibrateur sur sa plage de fréquences de fonctionnement. Cela garantit que le vibrateur fonctionne dans des limites sûres, ce qui évite les dommages et maximise la sortie de vibration.

Attention : Il existe différentes méthodes pour déterminer cette courbe, mais il est essentiel de s'assurer que les tensions mesurées se situent dans la plage de fonctionnement sûre du matériel pour éviter tout dommage.

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

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

M est 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 la force du champ magnétique (B) et de la longueur du conducteur (L) de le moteur de vibration

Loc_coeff: coefficient de localisation pour 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 de vibration

MPhone : masse de l'appareil (par exemple, 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 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 rapport 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, et ce coefficient tient compte de ce type d'effet. Il est calculé comme suit :

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

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

Le framework Android prend 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) dans 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 obtenez ainsi M(V(f), f).
• Cette accélération calculée est 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, spécifiant une fréquence (en Hertz) et son accélération de sortie maximale correspondante (en G crête).

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 de la fréquence avec une accélération de sortie maximale. Par exemple, utilisez des étapes de 1 Hz dans la plage de +/- 10 Hz de cette fréquence.

Capacités et limites de l'appareil

Pour Android 16 et versions ultérieures, afin d'aider les développeurs à optimiser leurs effets PWLE et à garantir 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 primitive PWLE minimale ou maximale 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 tout PWLE primitif en millisecondes.
• getPwleV2PrimitiveDurationMaxMillis: récupère la durée maximale autorisée pour tout PWLE primitif 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 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 dépassant le maximum), le framework ajuste automatiquement l'effet pour qu'il s'inscrive dans les limites autorisées. Ce processus d'ajustement tente de préserver autant que possible l'intention et la sensation d'origine de la conception.

---

1. Les données de seuil sont converties à partir du seuil de déplacement dans la figure 1 de Bolanowski Jr., S. J., et al. "Four channels mediate the mechanical aspects of touch." Journal of the Acoustical Society of America 84(5): 1680-1694 (1988). Ce tutoriel en ligne explique la conversion entre l'amplitude d'accélération et l'amplitude de déplacement. ↩

2. Les données sont estimées à partir de la figure 8 de Verrillo, R. T., et al. "Sensation magnitude of vibrotactile stimuli." Perception &Psychophysics 6 : 366-372 (1969). ↩