Wdrażanie efektów kopertowych o liniowym przebiegu

Efekty PWLE to sekwencje punktów określających częstotliwość i przyspieszenie drgań w czasie. PWLE zapewniają bogatsze i bardziej dynamiczne wibracje.

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

• Podstawowy interfejs PWLE API: prosty, ale z ograniczeniami. Dobre rozwiązanie na szybki start. Jest ona dostępna na stronie BasicEnvelopeBuilder.
• Zaawansowany interfejs PWLE API: większa kontrola i elastyczność, wymaga wiedzy o haptyce i sprzęcie. Dostępne na stronie WaveformEnvelopeBuilder.

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

• Mapowanie częstotliwości na maksymalne przyspieszenie wyjściowe (FOAM): zawiera mapowanie częstotliwości drgań na maksymalne przyspieszenie wyjściowe, jakie można uzyskać na urządzeniu.
• Komponowanie 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, programiści mogą używać podstawowego interfejsu PWLE API zdefiniowanego za pomocą tych parametrów:

• Wartość intensywności z zakresu [0, 1] reprezentuje odczuwalną siłę wibracji. Na przykład wartość 0,5 jest postrzegana jako połowa maksymalnej intensywności globalnej, jaką może osiągnąć urządzenie.
• Wartość ostrości z zakresu [0, 1] określa wyrazistość wibracji. Niższe wartości oznaczają płynniejsze wibracje, a wyższe – bardziej wyraziste.
• 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 przebiegu, który zwiększa intensywność od niskiego do wysokiego tonu maksymalnej siły wibracji w ciągu 500 ms, a następnie zmniejsza ją do 0 ms (wyłącza) w ciągu 100 ms:

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 dotykowe, efekty PWLE muszą zaczynać się i kończyć z 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 przez nieciągłości w amplitudzie, które mogą negatywnie wpływać na percepcję haptyczną użytkownika.

Aby zapewnić spójne renderowanie efektu PWLE w ekosystemie Androida, platforma wymaga, aby urządzenia obsługujące tę funkcję mogły obsługiwać minimalny czas 10 ms między punktami PWLE i 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 różnych urządzeniach z Androidem.

Zaawansowany interfejs PWLE API

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

• Wartość Amplituda 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ładowy przebieg, który zwiększa amplitudę wibratora od zera do pełnej przy częstotliwości 120 Hz w ciągu 100 ms, utrzymuje ten stan przez 200 ms, a następnie 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

Platforma 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 zakresie obsługiwanym przez urządzenie, zgodnie z definicją FOAM urządzenia. Jeśli wartości przekroczą te limity, urządzenie nie będzie wibrować.

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

Dokładne przedstawienie częstotliwości urządzenia w celu uzyskania możliwości przyspieszenia wyjściowego 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 API PWLE i procesie ich generowania.

Omówienie mapowania

Urządzenia obsługujące efekty PWLE muszą udostępniać mapę częstotliwości wyjściowej akceleracji (FOAM). FOAM to struktura danych generowana przez HAL, która mapuje częstotliwość wibracji (w hercach) na maksymalne osiągalne przyspieszenie wyjściowe aktuatora (w G peak) przy tej częstotliwości. Ta mapa jest kluczowa do zrozumienia, jak zmienia się moc 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, w którym napięcie wejściowe jest ograniczone w pobliżu częstotliwości rezonansowej, aby chronić silnik:

Rysunek 1. Przykład FOAM dla typowego rezonansowego elementu wykonawczego.

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

• Określanie pełnego zakresu częstotliwości: FOAM określa pełny zakres częstotliwości urządzenia, podając minimalną i maksymalną obsługiwaną częstotliwość wibracji.
• Określanie wartości intensywności i ostrości: podstawowy interfejs PWLE API działa w skali percepcji człowieka w zakresie intensywności i ostrości, które są następnie mapowane na parametry częstotliwości i amplitudy sprzętu przy użyciu wartości przyspieszenia wyjściowego w FOAM. To mapowanie zapewnia renderowanie efektów haptycznych zgodnie z możliwościami sprzętu. Zakres ostrości jest określony przez minimalny próg percepcji i odpowiada częstotliwościom, przy których urządzenie może generować efekty haptyczne odczuwalne przez użytkowników. Framework mapuje wartości intensywności na amplitudę na podstawie docelowego przyspieszenia wyjściowego przy wybranej częstotliwości. Dzięki temu wybrany poziom intensywności zostanie osiągnięty przy zachowaniu możliwości urządzenia.
• Udostępnianie możliwości sprzętowych: FOAM jest udostępniany deweloperom w VibratorFrequencyProfile, co zapewnia pełną częstotliwość wyjściowego zbioru danych o przyspieszeniu, 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 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 podstawowego interfejsu API koperty, dzięki czemu wibracje są wyczuwalne dla użytkownika. Ten zakres odpowiada częstotliwościom, przy których przyspieszenie wyjściowe jest co najmniej 10 dB powyżej progu wykrywania przez człowieka (czyli minimalnego poziomu postrzegalności) dla każdej częstotliwości. Dzięki temu wibracje będą wystarczająco silne, aby je poczuć.

Dodatkowo framework wykorzystuje dane 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 generowaniu wyczuwalnych wibracji na różnych urządzeniach.

Testy VTS mają na celu sprawdzenie, czy urządzenia obsługujące efekty obwiedni mają niepusty zakres częstotliwości, który generuje odczuwalne wibracje. Dzięki temu urządzenie może generować wibracje o wystarczającej intensywności, aby użytkownicy mogli je wyraźnie odczuwać.

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 metod getMinFrequencyHz i getMaxFrequencyHz.
• Maksymalne przyspieszenie wyjściowe: maksymalne osiągalne przyspieszenie wyjściowe urządzenia (w G) jest dostępne w getMaxOutputAccelerationGs.
• Mapowanie częstotliwości na przyspieszenie wyjściowe: getFrequenciesOutputAcceleration udostępnia mapowanie częstotliwości na przyspieszenie wyjściowe zaimplementowane w HAL.

Programiści 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ą znormalizować je do wartości z zakresu [0,0, 1,0] w stosunku do maksymalnego przyspieszenia wyjściowego urządzenia.

Zaawansowany interfejs PWLE API umożliwia deweloperom korzystanie 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 percepcji człowieka

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

Poniższy wykres przedstawia próg wykrywania ludzkiego postrzegania dotykowego¹ w przyspieszeniu w funkcji częstotliwości czasowej:

Rysunek 2. Próg wykrywania ludzkiego postrzegania dotykowego.

Aby użytkownicy mogli stale odczuwać efekty haptyczne, testy VTS sprawdzają, czy urządzenia z funkcjami kopertowania mają zakres częstotliwości, który może generować amplitudy wibracji przekraczające próg wykrywania przez człowieka o 10 dB.

Odczuwalna siła wibracji a amplituda przyspieszenia wibracji

Ludzkie postrzeganie intensywności wibracji (miara percepcji) nie rośnie liniowo wraz z amplitudą wibracji (parametr fizyczny). Interfejs PWLE API zakłada, że gdy projektant lub programista myśli o zmianach siły wibracji, oczekuje, że postrzegana intensywność będzie zgodna z funkcją PWLE. Odczuwalna 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 drgań (w G szczytowym) można obliczyć w ten sposób:

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

gdzie amplituda dB to suma poziomu źródła 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 ludzkiego postrzegania dotykowego (0 dB SL) w funkcji częstotliwości czasowej.

Rysunek 3. Poziomy przyspieszenia wibracji.

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

Ta sekcja zawiera ogólne wytyczne dotyczące uzyskiwania z urządzenia krzywej częstotliwości do maksymalnego przyspieszenia wyjściowego, która jest używana do generowania danych FOAM.

Uzyskaj krzywą maksymalnego napięcia (V)

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

Jeśli sprzęt ma funkcję ograniczenia 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żesz obliczyć za pomocą różnych metod. W tej sekcji opisujemy 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 w odpowiadającą mu maksymalną wartość przyspieszenia wyrażoną w G peak.

Podstawowe równanie używane w przypadku 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 zastosowany w aktuatorze haptycznym

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

Loc_coeff: Współczynnik lokalizacji do przekształcania 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 sterującego, obliczana jako:

\(w = 2 \pi f\)

Psys_abs: Odpowiedź amplitudowa układu masy, tłumika i sprężyny drugiego rzędu, obliczona jako:

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

Wnsys: częstotliwość drgań własnych układu drgającego;

Qsys: Współczynnik jakości układu wibracyjnego

Loc_coeff to stosunek przyspieszenia zmierzonego na poziomie telefonu do przyspieszenia zmierzonego na poziomie modułu. Ten współczynnik służy do przeliczania 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 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 2,5-krotne wzmocnienie.

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

Generowanie krzywej FOAM

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

• Dla każdej częstotliwości (f) w wybranym zakresie znajdź odpowiednie maksymalne napięcie V(f) na krzywej maksymalnego napięcia.
• Oblicz maksymalne przyspieszenie przy tej częstotliwości, korzystając z równania powyżej, wstawiając V(f) zamiast Vsys i odpowiednie f zamiast w. Dzięki temu uzyskasz M(V(f), f).
• Obliczone przyspieszenie to wartość FOAM(f).

Udostępnianie danych FOAM

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

Nie ma ścisłych wymagań dotyczących rozdzielczości FOAM, ale zalecamy definiowanie krzywych z jednym maksymalnym pikiem. W podstawowym interfejsie Envelope API do mapowania efektów wibracji używany jest tylko pierwszy pik. Aby zoptymalizować dokładność interpolacji liniowej podczas określania pośrednich wartości przyspieszenia, zalecamy zdefiniowanie wysokiej rozdzielczości częstotliwości w pobliżu wartości szczytowej. Na przykład używaj kroków o wartości 1 Hz w zakresie +/- 10 Hz od częstotliwości szczytowej.

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ść na różnych urządzeniach, Android zawiera interfejsy API HAL do sprawdzania możliwości PWLE urządzenia. Te metody dostarczają informacji o ograniczeniach urządzenia, takich jak minimalny lub maksymalny czas trwania elementu PWLE oraz liczba elementów dozwolonych w kompozycji PWLE.

Interfejsy API HAL obejmują:

• CAP_COMPOSE_PWLE_EFFECTS_V2: zwracana przez IVibrator.getCapabilities, gdy urządzenie obsługuje tę funkcję.
• getFrequencyToOutputAccelerationMap: pobiera dane FOAM.
• getPwleV2PrimitiveDurationMinMillis: pobiera minimalny czas trwania dozwolony w przypadku dowolnego podstawowego elementu PWLE (w milisekundach).
• getPwleV2PrimitiveDurationMaxMillis: pobiera maksymalny czas trwania dowolnego podstawowego elementu PWLE (w milisekundach).
• getPwleV2CompositionSizeMax: pobiera maksymalną liczbę elementó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 do 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), platforma automatycznie dostosowuje efekt, aby mieścił się w dozwolonych granicach. Ten proces dostosowywania ma na celu jak największe zachowanie pierwotnego zamysłu i charakteru projektu.