Menerapkan efek amplop linear terpisah

Efek envelope linear terpisah (PWLE) adalah urutan titik yang menentukan frekuensi dan akselerasi getaran dari waktu ke waktu. PWLE menawarkan feedback 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. Cocok untuk memulai dengan cepat. Fitur ini tersedia di BasicEnvelopeBuilder.
• PWLE API Lanjutan: Lebih banyak kontrol dan fleksibilitas, memerlukan pengetahuan haptik dan beberapa pengetahuan tentang hardware. Tersedia di WaveformEnvelopeBuilder.

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

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

API PWLE Dasar

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 intensitas maksimum global yang dapat dicapai oleh perangkat.
• Nilai Ketajaman dalam rentang [0, 1] mewakili ketajaman getaran. Nilai yang lebih rendah akan menghasilkan getaran yang lebih halus, sedangkan nilai yang lebih tinggi akan menghasilkan sensasi yang lebih tajam.
• Durasi adalah waktu yang diperlukan untuk bertransisi dari titik PWLE terakhir (yaitu pasangan intensitas dan ketajaman) ke titik baru, dalam milidetik.

Berikut adalah contoh bentuk gelombang yang meningkatkan intensitas dari nada rendah ke getaran kekuatan maksimum nada tinggi selama 500 md, lalu menurun ke 0 (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 haptic yang lancar dan tanpa hambatan, efek PWLE harus dimulai dan diakhiri dengan intensitas 0,0. API menerapkan hal ini dengan menetapkan intensitas awal ke 0 dan 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 ms antara 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 Amplitude dalam rentang [0, 1] mewakili kekuatan yang dapat dicapai pada frekuensi tertentu, seperti yang ditentukan oleh FOAM perangkat. Misalnya, nilai 0,5 menghasilkan setengah 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 menaikkan amplitudo vibrator dari nonaktif ke penuh pada 120 Hz selama 100 milidetik, mempertahankan status tersebut selama 200 milidetik, lalu menaikkan kembali selama 100 milidetik:

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 disediakan 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, seperti yang ditentukan oleh FOAM perangkat. Jika nilai melebihi batas ini, perangkat tidak akan memutar getaran apa pun.

Pemetaan frekuensi ke output akselerasi (FOAM)

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

Memahami pemetaan

Perangkat yang mendukung efek PWLE perlu memberikan frekuensi untuk menghasilkan peta akselerasi (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 resonansi standar, dengan voltase input yang dibatasi di sekitar frekuensi resonansi untuk melindungi motor:

Gambar 1. Contoh FOAM untuk aktuator resonan 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 di FOAM. Pemetaan ini membantu memastikan bahwa 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 haptic yang dapat dirasakan pengguna. Framework memetakan nilai Intensitas ke amplitudo berdasarkan akselerasi output target pada frekuensi yang dipilih. Hal ini membantu memastikan bahwa tingkat intensitas yang dipilih tercapai sekaligus tetap dalam kemampuan perangkat.
• Mengekspos kemampuan hardware: FOAM diekspos kepada developer di VibratorFrequencyProfile, yang memberikan frekuensi lengkap untuk menghasilkan set data akselerasi yang menjelaskan beberapa kemampuan haptic perangkat. Data ini memungkinkan developer menggunakan PWLE API lanjutan untuk membuat efek getaran kustom yang melampaui rentang intensitas dan ketajaman dasar yang ditentukan oleh framework.

FOAM dan API PWLE dasar

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

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

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

FOAM dan PWLE API lanjutan

FOAM diekspos kepada 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 akselerasi frekuensi ke output: getFrequenciesOutputAcceleration menyediakan pemetaan akselerasi frekuensi ke output seperti yang diterapkan di HAL.

Developer dapat menggunakan informasi ini saat membuat efek amplop dengan PWLE API lanjutan. Misalnya, saat menentukan akselerasi output (dalam G), nilai tersebut harus dinormalisasi 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 data FOAM yang disediakan harus aman untuk vibrator dan tidak melampaui kemampuannya.

Batas deteksi persepsi manusia

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

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

Gambar 2. Batas deteksi persepsi haptic manusia.

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

Intensitas getaran yang dirasakan versus amplitudo akselerasi getaran

Persepsi manusia tentang intensitas getaran (ukuran persepsi) tidak tumbuh 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 oleh tingkat sensasi (SL), yang ditentukan sebagai dB di atas nilai minimum deteksi pada frekuensi yang sama. Dengan demikian, amplitudo akselerasi getaran (dalam puncak G) dapat dihitung sebagai berikut:

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

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

Dengan cara ini, PWLE API memastikan bahwa intensitas yang dirasakan berubah secara linear antara pasangan titik kontrol berturut-turut.

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

Gambar 3. Tingkat akselerasi getaran.

Menentukan kurva akselerasi output maksimum ke frekuensi

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

Mendapatkan kurva tegangan maksimum (V)

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

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

Menghitung Percepatan maksimum (M)

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

Metode ini mengonversi voltase maksimum yang diterapkan pada frekuensi tertentu menjadi nilai akselerasi 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 ke aktuator haptik

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

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

Rsys: Hambatan listrik kumparan motor getaran

MPhone: Massa perangkat (misalnya, ponsel)

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

\(w = 2 \pi f\)

Psys_abs: Respons amplitudo dari sistem massa, peredam, dan pegas urutan kedua, yang dihitung sebagai:

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

Wnsys: Frekuensi alami sistem bergetar

Qsys: Faktor kualitas sistem getar

Loc_coeff adalah rasio akselerasi yang diukur di tingkat ponsel dengan akselerasi yang diukur di tingkat modul. Rasio ini digunakan untuk mengonversi pembacaan akselerasi tingkat modul menjadi pembacaan akselerasi tingkat ponsel yang setara. Pada tingkat ponsel, karena akselerasi sudut gerakan modul, akselerasi akan diperkuat, dan koefisien ini memperhitungkan jenis efek tersebut. Jumlah ini dihitung sebagai berikut:

\(\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. 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.

Membuat kurva FOAM

Gabungkan kurva voltase maksimum (V) dan penghitungan 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.
• Hitung akselerasi maksimum pada frekuensi tersebut menggunakan persamaan di atas, dengan mengganti V(f) untuk Vsys dan f yang sesuai untuk w. Tindakan ini akan 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 perantara, 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 dan memastikan kompatibilitas di seluruh perangkat, Android menyertakan HAL API untuk membuat kueri 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 saat 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 ditampilkan kepada developer agar mereka dapat menyesuaikan efeknya dengan kemampuan khusus perangkat target, terutama saat menggunakan PWLE API lanjutan.

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 intent dan nuansa desain asli sebanyak mungkin.