Menerapkan efek amplop linear terpisah

Efek amplop linear per bagian (PWLE) adalah urutan titik yang menentukan frekuensi dan akselerasi getaran dari waktu ke waktu. PWLE menawarkan umpan balik haptik yang lebih kaya dan dinamis.

Android 16 dan yang lebih tinggi menyediakan dua API developer aplikasi untuk membantu membuat efek PWLE:

• PWLE API Dasar: Sederhana, tetapi memiliki batasan. Bagus untuk memulai dengan cepat. Fitur ini tersedia di BasicEnvelopeBuilder.
• Advanced PWLE API: Kontrol dan fleksibilitas yang lebih besar, memerlukan pengetahuan haptik dan pemahaman tentang hardware. Tersedia di WaveformEnvelopeBuilder.

Untuk mendukung API ini, perangkat harus menerapkan HAL API berikut:

• Pemetaan akselerasi output ke frekuensi (FOAM): Menyediakan pemetaan frekuensi getaran ke akselerasi output maksimum yang dapat dicapai untuk perangkat.
• Compose PWLE: Memutar getaran yang ditentukan oleh PWLE bentuk gelombang getaran.

Basic PWLE API

Untuk cara cepat membuat efek PWLE tanpa mempelajari hardware atau nuansa persepsi manusia, developer dapat menggunakan PWLE API dasar, yang ditentukan menggunakan parameter berikut:

• Nilai Intensitas dalam rentang [0, 1] mewakili kekuatan getaran yang dirasakan. Misalnya, nilai 0,5 dianggap sebagai setengah dari intensitas maksimum global yang dapat dicapai oleh perangkat.
• Nilai Ketajaman dalam rentang [0, 1] merepresentasikan kejelasan getaran. Nilai yang lebih rendah menghasilkan getaran yang lebih halus, sedangkan nilai yang lebih tinggi menghasilkan sensasi yang lebih tajam.
• Durasi adalah waktu yang diperlukan untuk bertransisi dari titik PWLE terakhir (yaitu, pasangan intensitas dan ketajaman) ke titik yang baru, dalam milidetik.

Berikut adalah contoh bentuk gelombang yang meningkatkan intensitas dari nada rendah ke nada tinggi dengan getaran berkekuatan maksimum selama 500 md, lalu menurun ke 0 md (nonaktif) selama 100 md:

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

Batasan

Untuk menciptakan pengalaman haptik yang lancar dan mulus, efek PWLE harus dimulai dan diakhiri dengan intensitas 0,0. API menerapkan hal ini dengan memperbaiki intensitas awal pada 0 dan akan menampilkan pengecualian jika intensitas akhir bukan 0. Batasan ini mencegah efek dinamis yang tidak diinginkan dalam getaran karena diskontinuitas dalam amplitudo yang dapat berdampak negatif pada persepsi haptik pengguna.

Untuk memastikan rendering efek PWLE yang konsisten di seluruh ekosistem Android, framework mewajibkan perangkat yang mendukung fitur ini dapat menangani durasi minimum 10 md antar-titik PWLE dan minimal 16 titik untuk efek PWLE. Persyaratan ini diterapkan oleh pengujian VTS, yang membantu memastikan efek PWLE yang andal di seluruh perangkat Android.

Advanced PWLE API

Developer dengan pengetahuan lanjutan dalam haptik dapat menentukan efek PWLE menggunakan kriteria berikut:

• Nilai Amplitudo dalam rentang [0, 1] menunjukkan kekuatan yang dapat dicapai pada frekuensi tertentu, sebagaimana ditentukan oleh FOAM perangkat. Misalnya, nilai 0,5 menghasilkan setengah dari akselerasi output maksimum yang dapat dicapai pada frekuensi tertentu.
• Frekuensi ditentukan langsung dalam Hertz.
• Durasi adalah waktu yang diperlukan untuk bertransisi dari titik PWLE terakhir ke titik baru, dalam milidetik.

Berikut adalah contoh bentuk gelombang yang meningkatkan vibrator dari nonaktif ke amplitudo penuh pada 120 Hz selama 100 md, mempertahankan status tersebut selama 200 md, lalu menurun kembali selama 100 md:

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

Batasan

Framework tidak mengubah nilai frekuensi dan amplitudo yang diminta yang diberikan oleh developer, tetapi menambahkan titik awal amplitudo 0 untuk memastikan transisi yang lancar.

Developer bertanggung jawab untuk memastikan bahwa frekuensi yang ditentukan dalam efek PWLE mereka berada dalam rentang yang didukung perangkat, sebagaimana ditentukan oleh FOAM perangkat. Jika nilai melebihi batas ini, perangkat tidak memutar getaran apa pun.

Frekuensi untuk memetakan akselerasi output (FOAM)

Representasi akurat frekuensi perangkat untuk menghasilkan kemampuan akselerasi sangat penting untuk mendukung PWLE API. Bagian ini menjelaskan pentingnya data ini, cara data ini digunakan oleh PWLE API, dan proses pembuatannya.

Memahami pemetaan

Perangkat yang mendukung efek PWLE perlu menyediakan peta akselerasi output frekuensi (FOAM). FOAM adalah struktur data yang dihasilkan oleh HAL yang memetakan frekuensi getaran (dalam Hertz) ke akselerasi output maksimum yang dapat dicapai aktuator (dalam puncak G) pada frekuensi tersebut. Peta ini sangat penting untuk memahami bagaimana output getaran bervariasi untuk rentang frekuensi yang didukung, dan untuk menentukan PWLE API dasar.

Plot berikut menunjukkan contoh FOAM untuk aktuator resonan umum, dengan voltase input dibatasi di sekitar frekuensi resonan untuk melindungi motor:

Gambar 1. Contoh FOAM untuk aktuator resonansi standar.

FOAM memiliki tiga tujuan utama:

• Menentukan rentang frekuensi penuh: FOAM menentukan rentang frekuensi penuh perangkat dengan menentukan frekuensi getaran minimum dan maksimum yang didukung.
• Menentukan nilai intensitas dan ketajaman: PWLE API dasar beroperasi pada skala persepsi manusia untuk intensitas dan ketajaman, yang kemudian dipetakan ke parameter frekuensi dan amplitudo hardware menggunakan nilai akselerasi output dalam FOAM. Pemetaan ini membantu memastikan efek haptik dirender sesuai dengan kemampuan hardware. Rentang ketajaman ditentukan oleh batas minimum yang dapat dirasakan dan sesuai dengan frekuensi saat perangkat dapat menghasilkan efek haptik yang dapat dirasakan pengguna. Framework memetakan nilai Intensitas ke amplitudo berdasarkan target percepatan output pada frekuensi yang dipilih. Hal ini membantu memastikan bahwa tingkat intensitas yang dipilih tercapai sekaligus tetap berada dalam kemampuan perangkat.
• Mengekspos kemampuan hardware: FOAM diekspos ke developer di VibratorFrequencyProfile, yang menyediakan frekuensi lengkap untuk menghasilkan set data akselerasi yang menjelaskan beberapa kemampuan haptic perangkat. Data ini memungkinkan developer yang menggunakan PWLE API tingkat lanjut untuk membuat efek getaran kustom yang melampaui rentang intensitas dan ketajaman dasar yang ditentukan oleh framework.

FOAM dan PWLE API dasar

FOAM memainkan peran penting dalam membentuk efek getaran. Parameter ini digunakan untuk menghitung rentang ketajaman untuk API amplop dasar, sehingga memastikan bahwa getaran dapat dirasakan oleh pengguna. Rentang ini sesuai dengan frekuensi saat akselerasi output tidak kurang dari 10 dB di atas nilai minimum yang dapat dirasakan manusia untuk setiap frekuensi. Hal ini memastikan bahwa getaran cukup kuat untuk dirasakan.

Selain itu, framework menggunakan data FOAM untuk memetakan nilai intensitas dan ketajaman yang digunakan dalam PWLE API dasar ke nilai amplitudo dan frekuensi yang sesuai. Pemetaan ini membantu menghasilkan umpan balik haptik yang dapat dirasakan di berbagai perangkat.

Pengujian VTS dilakukan untuk memastikan perangkat yang mendukung efek amplop memiliki rentang frekuensi tidak kosong yang menghasilkan getaran yang dapat dirasakan. Hal ini membantu memastikan bahwa perangkat dapat menghasilkan getaran dengan intensitas yang cukup agar dapat dirasakan dengan jelas oleh pengguna.

FOAM dan PWLE API lanjutan

FOAM diekspos ke developer oleh VibratorFrequencyProfile dengan informasi berikut:

• Rentang frekuensi: Developer dapat mengambil frekuensi minimum dan maksimum yang didukung perangkat, dalam Hertz, menggunakan getMinFrequencyHz dan getMaxFrequencyHz.
• Percepatan output maksimum: Percepatan output maksimum yang dapat dicapai perangkat (dalam G) tersedia melalui getMaxOutputAccelerationGs.
• Pemetaan frekuensi ke akselerasi output: getFrequenciesOutputAcceleration menyediakan pemetaan frekuensi ke akselerasi output sebagaimana diimplementasikan di HAL.

Developer dapat menggunakan informasi ini saat membuat efek amplop dengan PWLE API lanjutan. Misalnya, saat menentukan akselerasi output (dalam G), Anda harus menormalisasinya ke nilai dalam rentang [0.0, 1.0], relatif terhadap akselerasi output maksimum perangkat.

Dengan PWLE API lanjutan, developer dapat menggunakan seluruh rentang frekuensi, sehingga sangat penting agar data FOAM yang diberikan aman untuk vibrator dan tidak melebihi kemampuannya.

Nilai minimum deteksi persepsi manusia

Ambang batas deteksi persepsi manusia mengacu pada akselerasi minimum getaran yang dapat dideteksi secara andal oleh seseorang. Tingkat ini bervariasi berdasarkan frekuensi getaran.

Plot berikut menunjukkan nilai minimum deteksi persepsi haptik manusia¹, dalam percepatan, sebagai fungsi frekuensi temporal:

Gambar 2. Nilai minimum deteksi persepsi haptik manusia.

Agar pengguna dapat merasakan efek haptik secara konsisten, pengujian VTS memvalidasi bahwa perangkat dengan kemampuan amplop memiliki rentang frekuensi yang dapat menghasilkan amplitudo getaran yang melebihi nilai minimum deteksi persepsi manusia sebesar 10 dB.

Intensitas getaran yang dirasakan versus amplitudo percepatan getaran

Persepsi manusia terhadap intensitas getaran (ukuran persepsi) tidak meningkat secara linear dengan amplitudo getaran (parameter fisik). PWLE API mengasumsikan bahwa saat desainer atau developer memikirkan perubahan kekuatan getaran, mereka mengharapkan intensitas yang dirasakan mengikuti PWLE. Intensitas yang dirasakan ditandai dengan tingkat sensasi (SL), yang ditentukan sebagai dB di atas batas deteksi pada frekuensi yang sama. Dengan demikian, amplitudo percepatan getaran (dalam puncak G) dapat dihitung sebagai berikut:

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

Dengan dB amplitudo adalah jumlah SL dan batas deteksi (nilai di sepanjang ordinat dalam plot berikut) pada frekuensi tertentu.

Dengan cara ini, PWLE API memastikan bahwa intensitas yang dirasakan berubah secara linear di antara pasangan titik kontrol yang berurutan.

Plot berikut menunjukkan tingkat percepatan getaran² pada 10, 20, 30, 40, dan 50 dB SL, beserta deteksi persepsi haptik manusia threshold (0 dB SL), sebagai fungsi frekuensi temporal.

Gambar 3. Tingkat akselerasi getaran.

Menentukan frekuensi ke kurva akselerasi output maksimum

Bagian ini memberikan panduan umum tentang cara mendapatkan kurva akselerasi output maksimum frekuensi dari perangkat, yang Anda gunakan untuk membuat data FOAM.

Dapatkan kurva voltase maksimum (V)

V adalah voltase maksimum yang dapat diterapkan dengan aman ke vibrator dalam rentang frekuensi operasinya. Hal ini memastikan vibrator beroperasi dalam batas yang aman, mencegah kerusakan, dan memaksimalkan output getaran.

Jika hardware menyertakan fitur batasan voltase, gunakan fitur tersebut untuk mengukur secara langsung voltase maksimum yang dapat dicapai di seluruh rentang frekuensi yang didukung.

Hitung Percepatan maksimum (M)

M adalah akselerasi maksimum, yang dapat Anda hitung melalui berbagai metodologi. Bagian ini menunjukkan satu metode untuk perangkat yang menggunakan aktuator resonansi linear (LRA).

Metode ini mengonversi voltase maksimum yang diterapkan pada frekuensi tertentu menjadi nilai percepatan maksimum yang sesuai, yang dinyatakan dalam puncak G.

Persamaan inti yang digunakan untuk konversi ini adalah:

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

Dalam hal ini:

Vsys: Tingkat voltase sebenarnya yang diterapkan pada aktuator haptik

BLsys: Hasil kali kekuatan medan magnet (B) dan panjang konduktor (L) dari motor getar

Loc_coeff: Koefisien lokasi untuk mengonversi akselerasi tingkat modul menjadi akselerasi tingkat ponsel

Rsys: Hambatan listrik pada kumparan motor getar

MPhone: Massa perangkat (misalnya, ponsel)

w: Frekuensi sudut (radian per detik) sinyal penggerak, dihitung sebagai:

\(w = 2 \pi f\)

Psys_abs: Respons amplitudo sistem massa, peredam, dan pegas orde kedua, dihitung sebagai:

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

Wnsys: Frekuensi alami sistem yang bergetar

Qsys: Faktor kualitas sistem getar

Loc_coeff adalah rasio akselerasi yang diukur di tingkat ponsel terhadap akselerasi yang diukur di tingkat modul. Rasio ini digunakan untuk mengonversi pembacaan akselerasi tingkat modul ke pembacaan akselerasi tingkat ponsel yang setara. Pada tingkat ponsel, karena percepatan sudut gerakan modul, percepatan diperkuat, dan koefisien ini memperhitungkan jenis efek tersebut. Hal ini dihitung sebagai:

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

Misalnya, jika akselerasi modul adalah 1 g dan akselerasi ponsel adalah 2,5 g, maka Loc_coeff = 2,5. Hal ini menunjukkan amplifikasi 2,5x.

Framework Android menggunakan frekuensi dalam satuan Hertz, sehingga HAL perlu mengonversi satuan frekuensi dari radian per detik ke Hertz saat membuat data FOAM.

Buat kurva FOAM

Gabungkan kurva voltase maksimum (V) dan perhitungan akselerasi (M) untuk menentukan kurva FOAM:

• Untuk setiap frekuensi (f) dalam rentang yang diinginkan, temukan voltase maksimum V(f) yang sesuai dari kurva voltase maksimum Anda.
• Hitung percepatan maksimum pada frekuensi tersebut menggunakan persamaan di atas, dengan mengganti V(f) dengan Vsys dan f yang sesuai dengan w. Hal ini memberi Anda M(V(f), f).
• Percepatan yang dihitung ini adalah nilai FOAM(f) Anda.

Mengekspos data FOAM

Setelah kurva FOAM dibuat, HAL akan merepresentasikan kurva sebagai daftar objek FrequencyAccelerationMapEntry. Setiap entri menentukan titik dalam pemetaan, yang menentukan frekuensi (dalam Hertz) dan akselerasi output maksimum yang sesuai (dalam puncak G).

Meskipun tidak ada persyaratan ketat untuk resolusi FOAM, sebaiknya tentukan kurva dengan satu puncak maksimum. Hanya puncak pertama yang digunakan dalam API amplop dasar untuk memetakan efek getaran. Untuk mengoptimalkan akurasi interpolasi linear saat menentukan nilai akselerasi menengah, sebaiknya tentukan resolusi frekuensi tinggi di sekitar puncak. Misalnya, gunakan langkah 1 Hz dalam rentang +/- 10 Hz dari frekuensi puncak.

Kemampuan dan batasan perangkat

Untuk Android 16 dan yang lebih tinggi, guna membantu developer mengoptimalkan efek PWLE mereka dan memastikan kompatibilitas di seluruh perangkat, Android menyertakan API HAL untuk mengkueri kemampuan PWLE perangkat. Metode ini memberikan informasi tentang batasan perangkat, seperti durasi primitif PWLE minimum atau maksimum dan jumlah primitif yang diizinkan dalam komposisi PWLE.

HAL API mencakup:

• CAP_COMPOSE_PWLE_EFFECTS_V2: Ditampilkan oleh IVibrator.getCapabilities jika perangkat mendukung fitur ini.
• getFrequencyToOutputAccelerationMap: Mengambil data FOAM.
• getPwleV2PrimitiveDurationMinMillis: Mengambil durasi minimum yang diizinkan untuk PWLE primitif dalam milidetik.
• getPwleV2PrimitiveDurationMaxMillis: Mengambil durasi maksimum yang diizinkan untuk PWLE primitif dalam milidetik.
• getPwleV2CompositionSizeMax: Mengambil jumlah maksimum primitif PWLE yang didukung oleh IVibrator.composePwleV2.

Informasi ini diekspos kepada developer agar mereka dapat menyesuaikan efeknya dengan kemampuan spesifik perangkat target, terutama saat menggunakan Advanced PWLE API.

Framework ini juga menggunakan API ini saat menangani efek yang dibuat dengan API dasar. Jika efek melebihi batasan perangkat (misalnya, terlalu banyak titik PWLE atau durasi yang melebihi maksimum), framework akan otomatis menyesuaikan efek agar sesuai dengan batas yang diizinkan. Proses penyesuaian ini mencoba mempertahankan maksud dan nuansa desain asli sebanyak mungkin.