Wdrażanie efektów kopertowych o liniowym przebiegu

Efekty PWLE (piecewise linear envelope) to sekwencje punktów określających częstotliwość i przyspieszenie wibracji w czasie. PWLE zapewniają bogatsze i bardziej dynamiczne reakcje haptyczne.

Android 16 i nowsze wersje udostępniają 2 interfejsy API dla deweloperów aplikacji, które pomagają tworzyć efekty PWLE:

• Podstawowy interfejs PWLE API: prosty, ale z ograniczeniami. Dobry do szybkiego rozpoczęcia pracy. Jest dostępny w BasicEnvelopeBuilder.
• Zaawansowany interfejs PWLE API: większa kontrola i elastyczność, wymaga wiedzy o haptyce i pewnej znajomości sprzętu. Dostępny w WaveformEnvelopeBuilder.

Aby obsługiwać te interfejsy API, urządzenia muszą implementować te interfejsy HAL API:

• Częstotliwość rezonansowa: podaje częstotliwość rezonansową siłownika.
• Mapowanie częstotliwości na przyspieszenie wyjściowe (FOAM): zapewnia mapowanie częstotliwości wibracji na maksymalne osiągalne przyspieszenie wyjściowe urządzenia.
• Compose PWLE: odtwarza wibracje zdefiniowane przez PWLE fali wibracji.

Podstawowy interfejs PWLE API

Aby szybko tworzyć efekty PWLE bez zagłębiania się w sprzęt ani niuanse ludzkiej percepcji, deweloperzy mogą używać podstawowego interfejsu PWLE API, który jest definiowany za pomocą tych parametrów:

• Wartość intensywności z zakresu [0, 1] reprezentuje postrzeganą siłę wibracji. Na przykład wartość 0,5 jest postrzegana jako połowa globalnej maksymalnej intensywności, jaką może osiągnąć urządzenie.
• Wartość ostrości z zakresu [0, 1] reprezentuje wyrazistość wibracji. Niższe wartości oznaczają płynniejsze wibracje, a wyższe – bardziej ostre.
• Czas trwania to czas przejścia od ostatniego punktu PWLE (czyli pary intensywności i ostrości) do nowego punktu w milisekundach.

Oto przykład fali, która w ciągu 500 ms zwiększa intensywność od niskiego do wysokiego tonu wibracji o maksymalnej sile, a następnie w ciągu 100 ms zmniejsza się do 0 (wyłącza się):

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

Ograniczenia

Aby zapewnić płynne i bezproblemowe wrażenia haptyczne, efekty PWLE muszą zaczynać się i kończyć intensywnością 0,0. Interfejs API wymusza to, ustawiając intensywność początkową na 0 i zgłaszając wyjątek, jeśli intensywność końcowa nie wynosi 0. To ograniczenie zapobiega niepożądanym efektom dynamicznym w wibracjach spowodowanym nieciągłościami w amplitudzie, które mogą negatywnie wpływać na percepcję haptyczną użytkownika.

Aby zapewnić spójne renderowanie efektów PWLE w całym ekosystemie Androida, framework wymaga, aby urządzenia obsługujące tę funkcję mogły obsługiwać minimalny czas trwania 20 ms między punktami PWLE i co najmniej 16 punktów dla efektów PWLE. Te wymagania są egzekwowane przez testy VTS, co pomaga zapewnić niezawodne efekty PWLE na urządzeniach z Androidem.

Zaawansowany interfejs PWLE API

Deweloperzy z zaawansowaną wiedzą na temat haptyki mogą definiować efekty PWLE za pomocą tych kryteriów:

• Wartość amplitudy z zakresu [0, 1] reprezentuje osiągalną siłę przy danej częstotliwości, określoną przez FOAM urządzenia. Na przykład wartość 0,5 generuje połowę maksymalnego przyspieszenia wyjściowego, które można osiągnąć przy danej częstotliwości.
• Częstotliwość jest określana bezpośrednio w hercach.
• Czas trwania to czas przejścia od ostatniego punktu PWLE do nowego punktu w milisekundach.

Oto przykład fali, która w ciągu 100 ms zwiększa amplitudę wibratora od 0 do pełnej amplitudy przy 120 Hz, utrzymuje ten stan przez 200 ms, a następnie w ciągu 100 ms zmniejsza się do 0:

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

Ograniczenia

Framework nie modyfikuje żądanych wartości częstotliwości i amplitudy podanych przez dewelopera, ale dodaje punkt początkowy o amplitudzie 0, aby zapewnić płynne przejście.

Deweloperzy są odpowiedzialni za to, aby częstotliwość określona w efektach PWLE mieściła się w obsługiwanym zakresie urządzenia, zgodnie z definicją w FOAM urządzenia. Jeśli wartości przekraczają te limity, urządzenie nie odtwarza żadnych wibracji.

Mapowanie częstotliwości na przyspieszenie wyjściowe (FOAM)

Dokładne przedstawienie możliwości urządzenia w zakresie częstotliwości i przyspieszenia wyjściowego jest niezbędne do obsługi interfejsów PWLE API. W tej sekcji opisujemy znaczenie tych danych, sposób ich wykorzystania przez interfejsy PWLE API oraz proces ich generowania.

Zrozumienie mapowania

Urządzenia obsługujące efekty PWLE muszą udostępniać mapowanie częstotliwości na przyspieszenie wyjściowe (FOAM). FOAM to struktura danych generowana przez HAL, która mapuje częstotliwość wibracji (w hercach) na maksymalne osiągalne przyspieszenie wyjściowe siłownika (w G peak) przy tej częstotliwości. To mapowanie jest niezbędne do zrozumienia, jak zmienia się wyjście wibracji w obsługiwanym zakresie częstotliwości, oraz do zdefiniowania podstawowego interfejsu PWLE API.

Poniższy wykres przedstawia przykład FOAM dla typowego siłownika rezonansowego z napięciem wejściowym ograniczonym w pobliżu częstotliwości rezonansowej, aby chronić silnik:

Rysunek 1. Przykład FOAM dla typowego siłownika rezonansowego.

FOAM pełni 3 główne funkcje:

• Definiowanie pełnego zakresu częstotliwości: FOAM definiuje pełny zakres częstotliwości urządzenia, określając minimalną i maksymalną obsługiwaną częstotliwość wibracji.
• Definiowanie wartości intensywności i ostrości: podstawowy interfejs PWLE API działa w skali percepcji ludzkiej dla intensywności i ostrości, które są następnie mapowane na parametry częstotliwości i amplitudy sprzętu za pomocą wartości przyspieszenia wyjściowego w FOAM. To mapowanie pomaga zapewnić, że efekty haptyczne są renderowane zgodnie z możliwościami sprzętu. Zakres ostrości jest definiowany przez minimalny próg percepcji i odpowiada częstotliwościom, przy których urządzenie może wytwarzać efekty haptyczne odczuwalne dla użytkowników. Framework mapuje wartości intensywności na amplitudę na podstawie docelowego przyspieszenia wyjściowego przy wybranej częstotliwości. Pomaga to zapewnić osiągnięcie wybranego poziomu intensywności przy jednoczesnym zachowaniu możliwości urządzenia.
• Udostępnianie możliwości sprzętu: FOAM jest udostępniany deweloperom w VibratorFrequencyProfile, co zapewnia pełny zbiór danych dotyczących częstotliwości i przyspieszenia wyjściowego , który zawiera szczegółowe informacje o niektórych możliwościach haptycznych urządzenia. Te dane umożliwiają deweloperom korzystającym z zaawansowanego interfejsu PWLE API tworzenie niestandardowych efektów wibracji, które wykraczają poza podstawowe zakresy intensywności i ostrości zdefiniowane przez framework.

FOAM i podstawowy interfejs PWLE API

FOAM odgrywa kluczową rolę w kształtowaniu efektów wibracji. Służy do obliczania zakresu ostrości dla podstawowego interfejsu API koperty, co zapewnia, że wibracje są odczuwalne dla użytkownika. Ten zakres odpowiada częstotliwościom, przy których przyspieszenie wyjściowe po raz pierwszy osiąga 10 dB powyżej progu wykrywania percepcji ludzkiej (czyli minimalnego poziomu percepcji), aż do momentu, gdy przyspieszenie wyjściowe jest ostatni raz powyżej tego progu. Ten zakres musi obejmować częstotliwość rezonansową siłownika.

Ponadto framework używa danych FOAM do mapowania wartości intensywności i ostrości używanych w podstawowym interfejsie PWLE API na odpowiadające im wartości amplitudy i częstotliwości. To mapowanie pomaga w wytwarzaniu odczuwalnych reakcji haptycznych na różnych urządzeniach.

Testy VTS zapewniają, że urządzenia obsługujące efekty obwiedni mają niepusty zakres częstotliwości, który wytwarza odczuwalne wibracje, oraz że zakres ten zawiera częstotliwość rezonansową siłownika. Pomaga to zapewnić, że urządzenie może wytwarzać wibracje o wystarczającej intensywności, aby były wyraźnie odczuwalne dla użytkowników.

FOAM i zaawansowany interfejs PWLE API

FOAM jest udostępniany deweloperom przez VibratorFrequencyProfile z tymi informacjami:

• Zakres częstotliwości: deweloperzy mogą pobrać minimalną i maksymalną obsługiwaną częstotliwość urządzenia w hercach za pomocą odpowiednio getMinFrequencyHz i getMaxFrequencyHz.
• Maksymalne przyspieszenie wyjściowe: maksymalne osiągalne przyspieszenie wyjściowe urządzenia (w G) jest dostępne za pomocą getMaxOutputAccelerationGs.
• Mapowanie częstotliwości na przyspieszenie wyjściowe: getFrequenciesOutputAcceleration udostępnia mapowanie częstotliwości na przyspieszenie wyjściowe zaimplementowane w HAL.

Deweloperzy mogą używać tych informacji podczas tworzenia efektów obwiedni za pomocą zaawansowanego interfejsu PWLE API. Na przykład podczas określania przyspieszenia wyjściowego (w G) muszą je znormalizować do wartości z zakresu [0,0, 1,0] względem maksymalnego przyspieszenia wyjściowego urządzenia.

Dzięki zaawansowanemu interfejsowi PWLE API deweloperzy mogą używać całego zakresu częstotliwości, dlatego ważne jest, aby podane dane FOAM były bezpieczne dla wibratora i nie przekraczały jego możliwości.

Próg wykrywania percepcji ludzkiej

Próg wykrywania percepcji ludzkiej odnosi się do minimalnego przyspieszenia wibracji, które człowiek może niezawodnie wykryć. Ten poziom różni się w zależności od częstotliwości wibracji.

Poniższy wykres przedstawia próg wykrywania percepcji haptycznej człowieka¹ w przyspieszeniu jako funkcję częstotliwości czasowej:

Rysunek 2. Próg wykrywania percepcji haptycznej człowieka.

Aby użytkownicy mogli konsekwentnie odczuwać efekty haptyczne, testy VTS sprawdzają, czy urządzenia z możliwościami obwiedni mają zakres częstotliwości, który może wytwarzać amplitudy wibracji przekraczające próg wykrywania percepcji ludzkiej o 10 dB.

Postrzegana intensywność wibracji a amplituda przyspieszenia wibracji

Percepcja intensywności wibracji przez człowieka (miara percepcji) nie rośnie liniowo z amplitudą wibracji (parametr fizyczny). Interfejs PWLE API zakłada, że gdy projektant lub deweloper myśli o zmianach siły wibracji, oczekuje, że postrzegana intensywność będzie zgodna z PWLE. Postrzegana intensywność jest charakteryzowana przez poziom odczuwania (SL), który jest definiowany jako dB powyżej progu wykrywania przy tej samej częstotliwości. Dlatego amplitudę przyspieszenia wibracji (w G peak) można obliczyć w ten sposób:

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

gdzie amplituda dB to suma SL i progu wykrywania (wartość na osi rzędnych na poniższym wykresie) przy określonej częstotliwości.

W ten sposób interfejs PWLE API zapewnia, że postrzegana intensywność zmienia się liniowo między kolejnymi parami punktów kontrolnych.

Poniższy wykres przedstawia poziomy przyspieszenia wibracji² przy 10, 20, 30, 40 i 50 dB SL wraz z progiem wykrywania percepcji haptycznej człowieka (0 dB SL) jako funkcję częstotliwości czasowej.

Rysunek 3. Poziomy przyspieszenia wibracji.

Określanie krzywej częstotliwości do maksymalnego przyspieszenia wyjściowego

W tej sekcji znajdziesz ogólne wskazówki dotyczące uzyskiwania z urządzenia krzywej częstotliwości do maksymalnego przyspieszenia wyjściowego, która służy do generowania danych FOAM.

Uzyskiwanie krzywej maksymalnego napięcia (V)

V to maksymalne napięcie, które można bezpiecznie przyłożyć do wibratora w jego zakresie częstotliwości roboczej. Zapewnia to, że wibrator działa w bezpiecznych granicach, co zapobiega uszkodzeniom i maksymalizuje wyjście wibracji.

Jeśli sprzęt zawiera funkcję ograniczenia napięcia, użyj jej do bezpośredniego pomiaru maksymalnego osiągalnego napięcia w obsługiwanym zakresie częstotliwości.

Obliczanie maksymalnego przyspieszenia (M)

M to maksymalne przyspieszenie, które można obliczyć za pomocą różnych metod. W tej sekcji przedstawiamy jedną z metod dla urządzeń korzystających z liniowych siłowników rezonansowych (LRA).

Ta metoda przekształca maksymalne przyłożone napięcie przy danej częstotliwości na odpowiadającą mu maksymalną wartość przyspieszenia wyrażoną w G peak.

Podstawowe równanie używane do tej konwersji to:

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

Gdzie:

Vsys: rzeczywisty poziom napięcia przyłożonego do siłownika haptycznego

BLsys: iloczyn siły pola magnetycznego (B) i długości przewodnika (L) silnika wibracji

Loc_coeff: współczynnik lokalizacji do przekształcania przyspieszenia na poziomie modułu na przyspieszenie na poziomie telefonu

Rsys: opór elektryczny cewki silnika wibracji

MPhone: masa urządzenia (np. telefonu)

w: częstotliwość kątowa (radiany na sekundę) sygnału sterującego, obliczana jako:

\(w = 2 \pi f\)

Psys_abs: odpowiedź amplitudy systemu masy, tłumika i sprężyny drugiego rzędu, obliczana jako:

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

Wnsys: częstotliwość naturalna systemu wibracji

Qsys: współczynnik jakości systemu wibracji

Loc_coeff to stosunek przyspieszenia zmierzonego na poziomie telefonu do przyspieszenia zmierzonego na poziomie modułu. Ten współczynnik służy do przekształcania odczytów przyspieszenia na poziomie modułu na równoważne odczyty przyspieszenia na poziomie telefonu. Na poziomie telefonu, ze względu na przyspieszenie kątowe ruchu modułu, przyspieszenie jest wzmacniane, a ten współczynnik uwzględnia ten typ efektu. Jest obliczany jako:

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

Jeśli na przykład przyspieszenie modułu wynosi 1 g, a przyspieszenie telefonu 2,5 g, to Loc_coeff = 2,5. Oznacza to wzmocnienie 2,5-krotne.

Framework Androida przyjmuje częstotliwość w hercach, dlatego podczas generowania danych FOAM HAL musi przekształcić jednostkę częstotliwości z radianów na sekundę na herce.

Generowanie krzywej FOAM

Połącz krzywą maksymalnego napięcia (V) i obliczenie przyspieszenia (M), aby określić krzywą FOAM:

• Dla każdej częstotliwości (f) w żądanym zakresie znajdź odpowiednie maksymalne napięcie V(f) na krzywej maksymalnego napięcia.
• Oblicz maksymalne przyspieszenie przy tej częstotliwości za pomocą powyższego równania, podstawiając V(f) za Vsys i odpowiednie f za w. Otrzymasz M(V(f), f).
• To obliczone przyspieszenie jest wartością FOAM(f).

Udostępnianie danych FOAM

Po wygenerowaniu krzywej FOAM HAL przedstawia ją jako listę obiektów FrequencyAccelerationMapEntry. Każdy wpis definiuje punkt w mapowaniu, określając częstotliwość (w hercach) i odpowiadające jej maksymalne przyspieszenie wyjściowe (w G peak).

Aby zoptymalizować dokładność interpolacji liniowej podczas określania pośrednich wartości przyspieszenia, zalecamy zdefiniowanie wysokiej rozdzielczości częstotliwości wokół częstotliwości z maksymalnym przyspieszeniem wyjściowym. Na przykład użyj kroków 1 Hz w zakresie +/- 10 Hz tej częstotliwości.

Możliwości i ograniczenia urządzenia

W Androidzie 16 i nowszych wersjach, aby pomóc deweloperom w optymalizacji efektów PWLE i zapewnić zgodność z różnymi urządzeniami, Android zawiera interfejsy HAL API do sprawdzania możliwości PWLE urządzenia. Te metody dostarczają informacji o ograniczeniach urządzenia, takich jak minimalny lub maksymalny czas trwania prymitywu PWLE oraz liczba prymitywów dozwolonych w kompozycji PWLE.

Interfejsy HAL API obejmują:

• CAP_COMPOSE_PWLE_EFFECTS_V2: zwracany przez IVibrator.getCapabilities, gdy urządzenie obsługuje tę funkcję.
• getFrequencyToOutputAccelerationMap: pobiera dane FOAM.
• getPwleV2PrimitiveDurationMinMillis: pobiera minimalny dozwolony czas trwania dowolnego prymitywu PWLE w milisekundach.
• getPwleV2PrimitiveDurationMaxMillis: pobiera maksymalny dozwolony czas trwania dowolnego prymitywu PWLE w milisekundach.
• getPwleV2CompositionSizeMax: pobiera maksymalną liczbę prymitywów PWLE obsługiwanych przez IVibrator.composePwleV2.

Te informacje są udostępniane deweloperom, aby mogli dostosowywać efekty do konkretnych możliwości urządzenia docelowego, zwłaszcza podczas korzystania z zaawansowanego interfejsu PWLE API.

Framework używa też tych interfejsów API podczas obsługi efektów utworzonych za pomocą podstawowego interfejsu API. Jeśli efekt przekracza ograniczenia urządzenia (np. zbyt wiele punktów PWLE lub czas trwania przekraczający maksimum), framework automatycznie dostosowuje efekt do dozwolonych granic. Ten proces dostosowywania stara się jak najbardziej zachować pierwotny zamiar i charakter projektu.