Wdrażanie efektów kopertowych o liniowym przebiegu

Efekty sekcji liniowych (PWLE) to sekwencje punktów określające częstotliwość i przyspieszenie drgań w czasie. PWLE zapewniają bardziej szczegółowe i dynamiczne informacje haptyczne.

Android 16 i nowsze wersje udostępniają 2 interfejsy API dla programistów aplikacji, które ułatwiają tworzenie efektów PWLE:

• Podstawowy interfejs PWLE API: prosty, ale z ograniczeniami. Dobre rozwiązanie na początek, aby szybko zacząć korzystać z usługi. Ta funkcja jest dostępna na stronie BasicEnvelopeBuilder.
• Zaawansowany interfejs PWLE API: zapewnia większą kontrolę i elastyczność, wymaga znajomości haptyki i niewielkiej znajomości sprzętu. Dostępne na stronie WaveformEnvelopeBuilder.

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

• Mapowanie częstotliwości na przyspieszenie wyjścia (FOAM): umożliwia mapowanie częstotliwości wibracji na maksymalne możliwe przyspieszenie wyjścia urządzenia.
• Utwórz PWLE: odtwarza wibracje zdefiniowane przez PWLE sygnału wibracji.

Podstawowe interfejsy API PWLE

Aby szybko tworzyć efekty PWLE bez zagłębiania się w sprzęt lub subtelności ludzkiego postrzegania, deweloperzy mogą korzystać z podstawowego interfejsu PWLE API zdefiniowanego za pomocą tych parametrów:

• Wartość intensywności z zakresu [0, 1] odpowiada odczuwanej sile wibracji. Wartość 0,5 jest postrzegana jako połowa maksymalnej globalnej intensywności, jaką może osiągnąć urządzenie.
• Wartość ostrości z zakresu [0, 1] wskazuje wyrazistość wibracji. Niższe wartości oznaczają łagodniejsze 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 poziomu wibracji o maksymalnej mocy, a potem w ciągu 100 ms zmniejsza ją do 0 (wyłączenie):

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 działanie haptyczne, efekty PWLE muszą zaczynać się i kończyć z intensywnością 0,0. Interfejs API wymusza to, ustawiając początkową intensywność na 0 i wyrzucając wyjątek, jeśli końcowa intensywność nie jest równa 0. Ta ograniczenie zapobiega niepożądanym efektom dynamicznym wibracji spowodowanym przez nieciągłości w amplitudach, które mogą negatywnie wpływać na percepcję haptyczną użytkownika.

Aby zapewnić spójne renderowanie efektów PWLE w całym ekosystemie Androida, platforma wymaga, aby urządzenia obsługujące tę funkcję mogły obsłużyć co najmniej 10 ms między punktami PWLE oraz co najmniej 16 punktów dla efektów PWLE. Wymagania te są egzekwowane przez testy VTS, co pomaga zapewnić niezawodne działanie efektów PWLE na urządzeniach z Androidem.

Zaawansowane API PWLE

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ą moc przy danej częstotliwości, określoną przez FOAM urządzenia. Na przykład wartość 0,5 powoduje połowę maksymalnego przyspieszenia wyjściowego, jakie można uzyskać przy danej częstotliwości.
• Częstotliwość jest określana bezpośrednio w hercach.
• Czas trwania to czas przejścia z ostatniego punktu PWLE do nowego w milisekundach.

Oto przykład fali, która zwiększa amplitudę wibratora z poziomu wyłączonego do pełnej amplitudy z częstotliwością 120 Hz w ciągu 100 ms, utrzymuje ten stan przez 200 ms, a potem zmniejsza amplitudę w ciągu 100 ms:

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

Ograniczenia

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

Deweloperzy są odpowiedzialni za to, aby częstotliwość określona w efekcie PWLE mieściła się w obsługiwanym zakresie urządzenia, określonym przez FOAM urządzenia. Jeśli wartości przekroczą te limity, urządzenie nie nie będzie wibrować.

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

Dokładne odwzorowanie częstotliwości urządzenia i przyspieszenia wyjścia jest niezbędne do obsługi interfejsów PWLE API. W tej sekcji znajdziesz szczegółowe informacje o znaczeniu tych danych, sposobie ich wykorzystywania przez interfejsy PWLE oraz procesie ich generowania.

Informacje o mapowaniu

Urządzenia obsługujące efekty PWLE muszą udostępnić mapę przyspieszenia częstotliwości wyjściowej (FOAM). FOAM to struktura danych wygenerowana przez HAL, która mapuje częstotliwość wibracji (w hercach) na maksymalne możliwe przyspieszenie wyjścia (w G szczytowych) przy tej częstotliwości. Ta mapa jest kluczowa do zrozumienia, jak zmienia się wibracja w przypadku obsługiwanego zakresu częstotliwości, oraz do definiowania podstawowego interfejsu PWLE API.

Wykres poniżej pokazuje przykład fali FOAM dla typowego aktuatora rezonansowego z napięciem wejściowym ograniczonym w pobliżu częstotliwości rezonansowej w celu ochrony silnika:

Rysunek 1. Przykład FOAM dla typowego aktuatora rezonansowego.

FOAM służy do 3 głównych celów:

• Definiowanie pełnego zakresu częstotliwości: FOAM definiuje pełny zakres częstotliwości urządzenia, podając obsługiwane minimalne i maksymalne częstotliwości wibracji.
• Definiowanie wartości intensywności i ostrości: podstawowe interfejs PWLE API działa na skali ludzkiego postrzegania 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. Dzięki temu efekty haptyczne są renderowane zgodnie z możliwościami sprzętu. Zakres ostrości jest zdefiniowany przez minimalny próg wyczuwalności i odpowiada częstotliwościom, przy których urządzenie może generować efekty haptyczne, które użytkownicy mogą odczuć. System mapuje wartości intensywności na podstawie docelowego przyspieszenia wyjścia przy wybranej częstotliwości. Dzięki temu można osiągnąć wybrany poziom intensywności, nie przekraczając możliwości urządzenia.
• Wyświetlanie możliwości sprzętowych: interfejs FOAM jest dostępny dla deweloperów w VibratorFrequencyProfile. Zawiera on pełny zbiór danych o przyspieszeniu od częstotliwości do wyjścia, który szczegółowo opisuje niektóre możliwości haptyczne urządzenia. Dane te umożliwiają deweloperom korzystającym z zaawansowanego interfejsu PWLE tworzenie niestandardowych efektów wibracji, które wykraczają poza podstawowe zakresy intensywności i ostrości zdefiniowane przez platformę.

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 obudowy, co zapewnia użytkownikowi odczuwalne wibracje. Ten zakres odpowiada częstotliwościom, dla których przyspieszenie wyjściowe jest co najmniej 10 dB powyżej progu wykrywania przez człowieka (czyli minimalnego poziomu wyczuwalności) dla każdej częstotliwości. Dzięki temu wibracje będą wyczuwalne.

Dodatkowo framework korzysta z danych FOAM, aby mapować wartości intensywności i ostrości używane w podstawowym interfejsie PWLE API na odpowiadające im wartości amplitudy i częstotliwości. Takie mapowanie pomaga w generowaniu wyczuwalnych informacji zwrotnych haptycznych na różnych urządzeniach.

Testy VTS mają na celu zapewnienie, że urządzenia obsługujące efekty Envelope będą miały niepusty zakres częstotliwości, który generuje wyczuwalne wibracje. Dzięki temu urządzenie może generować wibracje o wystarczającej intensywności, aby były wyraźnie odczuwalne dla użytkowników.

FOAM i zaawansowany interfejs PWLE API

VibratorFrequencyProfile udostępnia deweloperom interfejs FOAM, podając te informacje:

• Zakres częstotliwości: deweloperzy mogą pobrać minimalne i maksymalne obsługiwane częstotliwości urządzenia w Hz, odpowiednio za pomocą getMinFrequencyHz i getMaxFrequencyHz.
• Maksymalne przyspieszenie wyjściowe: maksymalne możliwe przyspieszenie wyjściowe urządzenia (w G) jest dostępne w getMaxOutputAccelerationGs.
• Mapowanie częstotliwości na przyspieszenie wyjścia: getFrequenciesOutputAcceleration zapewnia mapowanie częstotliwości na przyspieszenie wyjścia zaimplementowane w HAL.

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

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

Próg wykrywania ludzkiego postrzegania

Próg wykrywania przez człowieka odnosi się do minimalnego przyspieszenia wibracji, które człowiek może niezawodnie wykryć. Ten poziom zależy od częstotliwości wibracji.

Na wykresie poniżej pokazano próg wykrywania ludzkiego postrzegania haptycznego¹ w przyspieszeniu jako funkcji częstotliwości czasowej:

Rysunek 2. Próg wykrywania dotykowego odbioru człowieka.

Aby użytkownicy mogli odczuwać efekty haptyczne w sposób spójny, testy VTS sprawdzają, czy urządzenia z możliwością tworzenia ścieżek mają zakres częstotliwości, który może generować amplitudy wibracji przekraczające próg wykrywania przez człowieka o 10 dB.

Odbierana siła wibracji w stosunku do amplitudy przyspieszenia wibracji

Odbieranie przez człowieka intensywności wibracji (jako miara percepcji) nie wzrasta w prosto proporcjonalny sposób wraz z amplitudą wibracji (parametrem fizycznym). Interfejs PWLE API zakłada, że gdy projektant lub programista rozważa zmiany siły wibracji, oczekuje, że postrzegana intensywność będzie zgodna z PWLE. Odbierana intensywność jest charakteryzowana przez poziom wrażenia (SL), który jest zdefiniowany jako dB powyżej progu wykrywania na tej samej częstotliwości. A zatem amplitudę przyspieszenia drgań (w G szczytowych) można obliczyć w ten sposób:

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

Gdzie amplituda w dB jest sumą SL i progułu wykrywania (wartość na osi y na wykresie poniżej) przy danej częstotliwości.

Dzięki temu interfejs PWLE API zapewnia, że postrzegana intensywność zmienia się liniowo między kolejnymi parami punktów kontrolnych.

Na poniższym wykresie pokazano poziomy przyspieszenia wibracji² na poziomie 10, 20, 30, 40 i 50 dB SL oraz próg wykrywania wibracji przez człowieka (0 dB SL) jako funkcję częstotliwości czasowej.

Rysunek 3. Poziomy przyspieszenia wibracji.

Określ krzywą przyspieszenia od częstotliwości do maksymalnego wyjścia

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

Uzyskanie krzywej maksymalnego napięcia (V)

V to maksymalne napięcie, które może być bezpiecznie zastosowane do wibratora w zakresie częstotliwości roboczej. Dzięki temu wibrator działa w bezpiecznych granicach, co zapobiega uszkodzeniom i maksymalizuje poziom wibracji.

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

Oblicz maksymalne przyspieszenie (M)

M to maksymalne przyspieszenie, które można obliczyć za pomocą różnych metod. W tej sekcji opisaliśmy jedną metodę dotyczącą urządzeń korzystających z aktywacji rezonansowej (LRA).

Ta metoda konwertuje maksymalne zastosowane napięcie przy danej częstotliwości na odpowiadającą mu maksymalną wartość przyspieszenia wyrażoną w G.

Podstawowe równanie użyte w przypadku tej konwersji:

\(\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 zastosowany do aktuatora haptycznego

BLsys: iloczyn natężenia pola magnetycznego (B) i długości przewodu (L) silnika wibracyjnego

Loc_coeff: współczynnik lokalizacji służący do konwertowania przyspieszenia na poziomie modułu na przyspieszenie na poziomie telefonu

Rsys: opór elektryczny cewki silnika wibracyjnego

MPhone: masa urządzenia (np. telefonu)

w: częstotliwość kątowa (radiany na sekundę) sygnału napędowego, obliczona jako:

\(w = 2 \pi f\)

Psys_abs: amplituda odpowiedzi systemu składającego się z drugorzędnej masy, tłumika i sprężyny, obliczona jako:

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

Wnsys: naturalna częstotliwość układu wibrującego

Qsys: współczynnik jakości systemu wibracyjnego

Loc_coeff to stosunek przyspieszenia zmierzonego na poziomie telefonu do przyspieszenia zmierzonego na poziomie modułu. Ten współczynnik służy do konwertowania odczytów przyspieszenia na poziomie modułu na równoważne odczyty przyspieszenia na poziomie telefonu. Na poziomie telefonu przyspieszenie jest wzmacniane z powodu przyspieszenia kątowego ruchu modułu, a ten współczynnik uwzględnia ten rodzaj efektu. Jest on 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.

Platforma Android przyjmuje częstotliwość w jednostce herców, więc podczas generowania danych FOAM interfejs HAL musi przekształcić jednostkę częstotliwości z radianów na sekundę na herce.

Generowanie krzywej FOAM

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

• W przypadku każdej częstotliwości (f) w pożądanym zakresie znajdź odpowiadające jej maksymalne napięcie (V(f)) na krzywej maksymalnego napięcia.
• Oblicz maksymalne przyspieszenie przy tej częstotliwości za pomocą powyższego równania, zastępując V(f) wartością Vsys, a odpowiadającą wartość f wartością w. W ten sposób uzyskujesz M(V(f), f).
• To obliczone przyspieszenie to wartość FOAM(f).

Wyświetlanie danych FOAM

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

Chociaż nie ma ścisłych wymagań dotyczących rozdzielczości krzywej FOAM, zalecamy definiowanie krzywych z jednym maksymalnym szczytem. W interfejsie API podstawowej ścieżki dźwiękowej do mapowania efektów wibracji jest używany tylko pierwszy szczyt. Aby zoptymalizować dokładność interpolacji liniowej podczas określania wartości przyspieszenia pośredniego, zalecamy zdefiniowanie rozdzielczości o wysokiej częstotliwości wokół szczytu. Użyj na przykład kroków co 1 Hz w zakresie +/- 10 Hz od częstotliwości szczytowej.

Funkcje i ograniczenia urządzenia

W Androidzie 16 i nowszych, aby pomóc deweloperom zoptymalizować efekty PWLE i zapewnić zgodność na różnych urządzeniach, Android zawiera interfejsy HAL do wysyłania zapytań o możliwości PWLE urządzenia. Te metody dostarczają informacji o ograniczeniach urządzenia, takich jak minimalny lub maksymalny czas trwania PWLE primitive i liczba prymitywów dozwolonych w kompozycji PWLE.

Interfejsy HAL obejmują:

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

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

Framework używa tych interfejsów API również do obsługi efektów utworzonych za pomocą podstawowego interfejsu API. Jeśli efekt przekracza ograniczenia urządzenia (np. zbyt duża liczba punktów PWLE lub czas trwania przekraczający maksymalną wartość), framework automatycznie dostosowuje efekt, aby mieścił się w dozwolonych granicach. W ramach tego procesu staramy się w jak największym stopniu zachować pierwotny zamysł i charakter projektu.