Implémenter des constantes et des primitives

Les constantes et les primitives haptiques sont définies par le HAL du vibreur et mappées par le framework Android aux API publiques. Effectuez les vérifications suivantes pour déterminer si votre appareil répond à la configuration minimale requise pour implémenter le retour haptique :

Figure 2. Implémenter des effets

Figure 3. Implémenter des primitives

Implémenter des constantes

Les constantes haptiques de VibrationEffect peuvent être utilisées par les développeurs via VibrationEffect.createPredefined(). Vérifiez l'état d'implémentation des constantes haptiques suivantes.

Constantes haptiques	Emplacements et résumés
EFFECT_TICK, EFFECT_CLICK, EFFECT_HEAVY_CLICK, EFFECT_DOUBLE_CLICK	VibrationEffect class Les constantes haptiques dans VibrationEffect n'incluent aucune notion d'événements d'entrée et ne comportent aucun élément d'interface utilisateur. Les constantes incluent plutôt la notion de niveaux d'énergie, tels que EFFECT_CLICK et EFFECT_HEAVY_CLICK, qui sont appelés par createPredefined().

Les vibrations alternatives décrites ci-dessous sont effectuées sur les appareils qui n'implémentent pas les constantes VibrationEffect. Nous vous recommandons de mettre à jour ces configurations pour qu'elles fonctionnent de manière optimale sur ces appareils.

• EFFECT_CLICK

  Vibration de forme d'onde créée avec VibrationEffect.createWaveform et les timings configurés sur frameworks/base/core/res/res/values/config.xml##config_virtualKeyVibePattern.

• EFFECT_HEAVY_CLICK

  Vibration de forme d'onde créée avec VibrationEffect.createWaveform et les timings configurés à frameworks/base/core/res/res/values/config.xml##config_longPressVibePattern.

  • EFFECT_DOUBLE_CLICK

  Vibration de forme d'onde créée avec VibrationEffect.createWaveform et les timings (0, 30, 100, 30).

• EFFECT_TICK

  Vibration de forme d'onde créée avec VibrationEffect.createWaveform et les timings configurés sur frameworks/base/core/res/res/values/config.xml##config_clockTickVibePattern.

Figure 4. Implémenter des constantes de commentaires

Les constantes haptiques de HapticFeedbackConstants peuvent être utilisées par les développeurs via View.performHapticFeedback(). Vérifiez l'état des constantes de rétroaction publiques suivantes.

Constantes haptiques	Emplacements et résumés
CLOCK_TICK, CONTEXT_CLICK, KEYBOARD_PRESS, KEYBOARD_RELEASE, KEYBOARD_TAP, LONG_PRESS, TEXT_HANDLE_MOVE, VIRTUAL_KEY, VIRTUAL_KEY_RELEASE, CONFIRM, REJECT, GESTURE_START, GESTURE_END	Classe HapticFeedbackConstants Les constantes haptiques dans HapticFeedbackConstants aident les événements d'entrée avec certains éléments d'interface utilisateur, tels que KEYBOARD_PRESS et KEYBOARD_RELEASE, qui sont appelés par performHapticFeedback().

Implémenter des primitives

Les primitives haptiques dans VibrationEffect.Composition ont une intensité évolutive que les développeurs peuvent utiliser via addPrimitive(int primitiveId, float scale, int delay). Les primitives peuvent être divisées en deux catégories :

• Primitives courtes : primitives de courte durée, généralement inférieure à 20 ms. Il s'agit de CLICK, TICK et LOW_TICK.

• Primitives de chirp : primitives avec une amplitude et une fréquence variables, généralement avec une durée plus longue que les primitives courtes. Il s'agit de SLOW_RISE, QUICK_RISE, QUCK_FALL, THUD et SPIN.

Primitives Short

Les primitives courtes peuvent être décrites par le profil d'accélération de la sortie du moteur du vibreur. La fréquence absolue utilisée varie pour chaque primitive, en fonction de la fréquence de résonance de l'actionneur. Pour en savoir plus sur la configuration du matériel et les outils de mesure de la sortie, consultez Configurer l'équipement de test.

Le rapport impulsion/sonnerie (PRR, pulse to ring ratio) est une métrique de qualité intéressante pour les vibrations courtes. Il est illustré à la figure 5. Le PRR est défini comme le rapport entre l'impulsion principale, définie par le signal à l'intérieur de la fenêtre de durée où l'amplitude diminue jusqu'à 10 % de l'amplitude maximale, et l'impulsion de résonance, définie par le signal où l'amplitude diminue de 10 % de l'amplitude maximale à moins de 1 % de l'amplitude maximale. La formule du taux de couverture et de répétition est la suivante :

Pour en savoir plus sur le PRR, consultez Analyser la forme d'onde. Pour en savoir plus sur l'analyse et la comparaison des résultats, consultez Comparer les résultats à l'aide de la carte des performances.

Figure 5. Définition du ratio entre les pulsations et les sonneries

Appliquez des primitives courtes comme commentaires d'entrée utilisateur ou jouées dans des compositions plus longues pour créer des textures douces. Cela signifie qu'elles sont généralement déclenchées fréquemment et lues rapidement les unes après les autres. L'intensité perçue d'un seul primitif court peut renforcer l'intensité de l'effet global. Pour cette raison, calibrez un seul tick ou un tick primitif faible avec une composition plus grande, par exemple 100 ticks consécutifs.

Primitive de clic

Le clic primitif est un effet fort et net qui fonctionne généralement à proximité de la fréquence de résonance d'un appareil pour atteindre une puissance maximale en peu de temps. Il est plus fort et plus profond que les autres primitives, et fonctionne à son intensité maximale.

Si possible, utilisez la surmultiplication du moteur au début et le freinage actif à la fin pour obtenir un temps de montée et de descente du moteur court. Pour certains moteurs, l'utilisation d'une onde carrée au lieu d'une onde sinusoïdale peut permettre une accélération plus rapide. La figure 6 illustre un exemple de profil d'accélération de sortie pour la primitive de clic :

Figure 6. Exemple de profil d'accélération de sortie pour le clic primitif

Paramètre	Consigne
Durée	Cible : 12 ms Limite : < 30 ms
Accélération de la puissance maximale	Cible : 2 G Limite : > 1 G
Fréquence	À peu près à la fréquence de résonance

Primitive de coche (coche légère)

Le primitif de tic est un effet bref et net qui fonctionne généralement dans une plage de fréquences plus élevée. Cette primitive peut également être décrite comme un clic d'intensité moyenne à une fréquence plus élevée avec une queue courte. Les mêmes conseils s'appliquent pour obtenir un temps de montée court en utilisant le surrégime du moteur ou une onde carrée pour le début initial, et le freinage actif à l'arrêt. La figure 7 montre un exemple de profil d'accélération de sortie pour la primitive de tick :

Figure 7. Exemple de profil d'accélération de sortie pour le primitif de graduation

Paramètre	Consigne
Durée	Cible : 5 ms Limite : < 20 ms
Accélération de la puissance maximale	Cible : moitié de CLICK, 1 G Limite : entre 0,5 G et 1 G
Fréquence	Cible : 2 fois la fréquence de résonance Limite : < 500 Hz

Primitive à faible précision

La primitive de faible tic est une version plus douce et plus faible d'un tic léger, fonctionnant dans une plage de fréquences plus basse pour donner plus de corps à l'effet. Cette primitive peut également être décrite comme un clic d'intensité moyenne à basse fréquence, destiné à être utilisé de manière répétitive pour un retour dynamique. Les mêmes conseils s'appliquent pour obtenir un temps de montée court en utilisant la surmultiplication du moteur ou une onde carrée pour le début initial. La figure 8 montre un exemple de profil d'accélération de sortie pour la primitive à faible nombre de ticks :

Figure 8. Exemple de profil d'accélération de sortie pour un primitif à faible nombre de ticks

Paramètre	Consigne
Durée	Cible : 12 ms Limite : < 30 ms
Accélération de la puissance maximale	Cible : 1/4 de TICK, soit 0,25 G Limite : entre 0,2 G et 0,5 G
Fréquence	Cible : 2/3 de la fréquence de résonance Limite : < 100 Hz

Primitives Chirp

Les primitives Chirp peuvent être décrites par les signaux d'entrée pour le niveau de tension et la fréquence de vibration. L'accélération que le moteur est capable de produire à différentes gammes de fréquences varie en fonction de la courbe de réponse en fréquence de l'actionneur. Les plages de fréquences et les niveaux de tension doivent être ajustés pour chaque appareil.

Primitive de hausse lente

La montée lente est un balayage lent de l'amplitude et de la fréquence vers le haut, avec un début doux et une intensité de vibration qui augmente de manière constante tout au long du balayage. Il peut être implémenté par un balayage cohérent de l'amplitude et de la fréquence, en utilisant une plage de fréquences plus basse qui fonctionne hors résonance. La figure 9 montre les paramètres d'entrée et un exemple de profil d'accélération de sortie pour cette implémentation. (La ligne rouge correspond aux libellés d'amplitude à gauche et représente la variation de l'amplitude des vibrations au fil du temps. La ligne bleue correspond aux libellés de fréquence à droite et représente la variation de la fréquence de vibration au fil du temps.)

Figure 9. Paramètres d'entrée et exemple de profil d'accélération de sortie pour la primitive de montée lente

Si la réponse en fréquence du moteur est limitée (pas assez forte en dehors de sa fréquence de résonance), une autre implémentation consiste à effectuer un balayage sinusoïdal de 1/2x à 1x la fréquence de résonance. La résonance du moteur contribue à atteindre le pic du signal à la fin.

Paramètre	Consigne
Durée	Cible : 500 ms Tolérance : 20 ms
Accélération de la puissance maximale	Cible : 0,5 G Limite : entre 0,5 G et 1 G
Fréquence	Cible : 1/2 à 2/3 de la fréquence de résonance Autre solution : 1/2 de la fréquence de résonance

Primitive d'augmentation rapide

La montée rapide est une balayage d'amplitude et de fréquence vers le haut avec un début doux et une intensité de vibration qui augmente de manière constante tout au long du balayage. Les cibles de fréquence d'accélération et de vibration de la sortie doivent être les mêmes que celles de la primitive de montée lente, mais obtenues dans une durée plus courte. La figure 10 montre les paramètres d'entrée de vibration et un exemple de profil d'accélération de sortie pour la primitive d'augmentation lente. (La ligne rouge correspond aux libellés d'amplitude à gauche et représente la variation de l'amplitude des vibrations au fil du temps. La ligne bleue correspond aux libellés de fréquence à droite et représente la variation de la fréquence de vibration au fil du temps.)

Figure 10. Paramètres d'entrée et exemple de profil d'accélération de sortie pour la primitive d'augmentation rapide

Paramètre	Consigne
Durée	Cible : 150 ms Tolérance : 20 ms
Accélération de la puissance maximale	Cible : identique à SLOW_RISE Limite : identique à SLOW_RISE
Fréquence	Cible : identique à SLOW_RISE Autre option : identique à SLOW_RISE

Primitive de chute rapide

La chute rapide est un balayage vers le bas rapide en amplitude et en fréquence, avec un début doux. Vous pouvez utiliser une fréquence plus élevée comme point de départ pendant que le moteur augmente sa vitesse pour atteindre l'accélération de sortie maximale. La fréquence doit diminuer de manière constante tout au long du balayage, même pendant le temps de montée. La figure 11 montre les paramètres d'entrée et un exemple de profil d'accélération de sortie pour cette implémentation. (La ligne rouge correspond aux libellés d'amplitude à gauche et représente la variation de l'amplitude des vibrations au fil du temps. La ligne bleue correspond aux libellés de fréquence à droite et représente la variation de la fréquence de vibration au fil du temps.)

Figure 11 : Paramètres d'entrée et exemple de profil d'accélération de sortie pour la primitive de chute rapide

Paramètre	Consigne
Durée	Cible : 100 ms Tolérance : 20 ms
Accélération de la puissance maximale	Cible : 1 G Limite : entre 0,5 G et 2 G
Fréquence	Cible : 1 à 2 fois la fréquence de résonance

Primitive "Thud"

Le bruit sourd est un effet de percussion grave qui simule la sensation physique de frapper sur du bois creux. Cette primitive fonctionne dans une plage de basse fréquence, semblable à la primitive de tic lent, pour donner plus de corps à l'effet. Vous pouvez implémenter la primitive de bruit sourd en tant que balayage descendant d'amplitude et de fréquence dans une plage de fréquences plus basses (de préférence inférieure à 100 Hz). La figure 12 montre les paramètres d'entrée et un exemple de profil d'accélération de sortie pour cette implémentation. (La ligne rouge correspond aux libellés d'amplitude à gauche et représente la variation de l'amplitude des vibrations au fil du temps. La ligne bleue correspond aux libellés de fréquence à droite et représente la variation de la fréquence de vibration au fil du temps.)

Figure 12. Paramètres d'entrée et exemple de profil d'accélération de sortie pour la primitive "thud"

Si la réponse en fréquence du moteur est limitée, une autre implémentation consiste à commencer par un signal d'entraînement à pleine intensité à la fréquence de résonance et à descendre à la fréquence la plus basse possible qui peut encore être perçue. Cette approche peut nécessiter une augmentation de l'intensité du signal d'entraînement à la fréquence inférieure pour que la vibration soit ressentie.

Paramètre	Consigne
Durée	Cible : 300 ms Tolérance : 20 ms
Accélération de la puissance maximale	Cible : 0,25 G Limite : entre 0,2 G et 0,5 G
Fréquence	Cible : 1/2 à 1/3 de la fréquence de résonance Autre option : 1 fois à 1/2 fois la fréquence de résonance

Primitive de rotation

La rotation simule un élan de rotation rapide de haut en bas avec un léger accent au centre. La rotation peut être implémentée en balayant l'amplitude et la fréquence de manière indépendante, dans des directions opposées, puis en inversant le mouvement. Il est important d'utiliser une plage de fréquences plus basse (de préférence inférieure à 100 Hz). La figure 13 montre les paramètres d'entrée et un exemple de profil d'accélération de sortie pour cette implémentation. (La ligne rouge correspond aux libellés d'amplitude à gauche et représente la variation de l'amplitude des vibrations au fil du temps. La ligne bleue correspond aux libellés de fréquence à droite et représente la variation de la fréquence de vibration au fil du temps.)

Nous vous recommandons d'appeler le primitif de rotation deux fois de suite ou trois fois dans les compositions pour obtenir une sensation de rotation et d'instabilité.

Si la réponse en fréquence du moteur est limitée, une autre implémentation consiste à effectuer un balayage sinusoïdal rapide de 1/2x à 1x la fréquence de résonance, puis à revenir en arrière. La résonance du moteur accentue automatiquement le signal au milieu.

Figure 13. Paramètres d'entrée et exemple de profil d'accélération de sortie pour le spin primitif

Paramètre	Consigne
Durée	Cible : 150 ms Tolérance : 20 ms
Accélération de la puissance maximale	Cible : 0,5 G Limite : entre 0,25 G et 0,75 G
Fréquence	Cible : 2/3 à 1/3, puis retour à 1/2 de la fréquence de résonance Autre solution : 2/3 à 1x, puis retour à 1/2 de la fréquence de résonance