הטמעת אפקטים של מעטפות ליניאריות רציפות

אפקטים של מעטפת לינארית חלקית (PWLE) הם רצפים של נקודות שמגדירות את תדירות הרטט ואת האצה לאורך זמן. באפליקציות PWA יש משוב מגע עשיר ודינמי יותר.

ב-Android מגרסה 16 ואילך יש שני ממשקי API למפתחי אפליקציות שעוזרים ליצור אפקטים של PWLE:

• Basic PWLE API: פשוט, אבל עם מגבלות. מתאים להתחיל במהירות. אפשר למצוא אותו בכתובת BasicEnvelopeBuilder.
• Advanced PWLE API: שליטה וגמישות רבה יותר, נדרש ידע בתחום ההאפטיקה והיכרות מסוימת עם חומרה. זמין בכתובת WaveformEnvelopeBuilder.

כדי לתמוך בממשקי ה-API האלה, המכשירים צריכים ליישם את ממשקי ה-API הבאים של HAL:

• מיפוי תדירות להאצה של הפלט (FOAM): מיפוי של תדירות הרטט להאצה המקסימלית של הפלט שניתן להשיג במכשיר.
• Compose PWLE: הפעלת רטט שמוגדר על ידי PWLE של צורת הגל של הרטט.

PWLE API בסיסי

כדי ליצור אפקטים של PWLE במהירות בלי להיכנס לפרטים של החומרה או לניואנסים של התפיסה האנושית, מפתחים יכולים להשתמש ב-PWLE API הבסיסי, שמוגדר באמצעות הפרמטרים הבאים:

• הערך של עוצמה בטווח [0, 1] מייצג את עוצמת הרטט שחושבים שהיא קיימת. לדוגמה, ערך של 0.5 נתפס כמחצית מהעוצמה המקסימלית הגלובלית שהמכשיר יכול להשיג.
• הערך של Sharpness בטווח [0, 1] מייצג את חדות הרטט. ערכים נמוכים יותר יוצרים רטט חלק יותר, ואילו ערכים גבוהים יותר יוצרים תחושה חדה יותר.
• משך זמן הוא הזמן שחלף מהנקודה האחרונה של PWLE (כלומר, הצמד של העוצמה והחדות) לנקודה החדשה, באלפיות שנייה.

בהמשך מוצגת דוגמה לצורת גל שמגבירה את העוצמה מצליל נמוך לצליל גבוה עם רטט בעוצמה מקסימלית במשך 500 אלפיות השנייה, ואז מפחיתה את העוצמה ל-0 (מושבת) במשך 100 אלפיות השנייה:

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

מגבלות

כדי ליצור חוויה חלקה ורציפות של משוב מישוש, חובה שהאפקט של PWLE יתחיל וייגמר בעוצמה של 0.0. ה-API אוכף את הכלל הזה על ידי קביעת עוצמת ההתחלה לערך 0 והשלפת חריגה אם עוצמת הסיום היא לא 0. האילוץ הזה מונע השפעות דינמיות לא רצויות ברעידות עקב הפסקות באמפליטודה שעלולות להשפיע לרעה על התפיסה החזותית של המשתמש.

כדי להבטיח עיבוד עקבי של אפקטים של PWLE בסביבת Android, המערכת מחייבת שמכשירים שתומכים בתכונה הזו יוכלו לטפל בפרק זמן מינימלי של 10 אלפיות שנייה בין נקודות PWLE, וב-16 נקודות לפחות לאפקטים של PWLE. הדרישות האלה נאכפות באמצעות בדיקות VTS, שעוזרות להבטיח אפקטים מהימנים של PWLE בכל מכשירי Android.

Advanced PWLE API

מפתחים עם ידע מתקדם בתחום ההאפטיקה יכולים להגדיר אפקטים של PWLE לפי הקריטריונים הבאים:

• הערך של Amplitude בטווח [0, 1] מייצג את עוצמת האות שאפשר להשיג בתדירות נתונה, כפי שנקבע על ידי FOAM של המכשיר. לדוגמה, ערך של 0.5 יוצר חצי מהתאוצה המקסימלית של הפלט שניתן להשיג בתדר הנתון.
• Frequency (תדירות) מצוין ישירות ב-Hertz.
• משך הוא הזמן שחלף מהנקודה האחרונה של PWLE לנקודה החדשה, באלפיות שנייה.

זו דוגמה לצורת גל שמפעילה ויברטור ממושבת לאמפליטודה מלאה של 120 Hz תוך 100 ms, שומרת על המצב הזה למשך 200 ms ואז מפחיתה את האמפליטודה תוך 100 ms:

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

מגבלות

המסגרת לא משנה את ערכי התדר והאמפליטודה המבוקשים שסופקו על ידי המפתח, אבל היא מוסיפה נקודת התחלה של אפס אמפליטודה כדי להבטיח מעבר חלק.

המפתחים אחראים לוודא שהתדר שצוין באפקטים של PWLE נמצא בטווח הנתמך של המכשיר, כפי שמוגדר על ידי FOAM של המכשיר. אם הערכים חורגים מהמגבלות האלה, המכשיר לא יפיק רטט.

מיפוי של תדירות ליצירת יציאה (FOAM)

כדי לתמוך בממשקי ה-API של PWLE, חיוני לייצג בצורה מדויקת את יכולות המכשיר להאיץ את תדירות הפלט. בקטע הזה מוסבר מה המשמעות של הנתונים האלה, איך ממשקי ה-API של PWLE משתמשים בהם ותהליך היצירה שלהם.

הסבר על המיפוי

במכשירים שתומכים באפקטים של PWLE צריך לספק תדירות למיפוי האצת הפלט (FOAM). ‏FOAM הוא מבנה נתונים שנוצר על ידי ה-HAL וממפה את תדירות הרטט (בהרץ) לתאוצה המקסימלית האפשרית של הפלט של המפעיל (ב-G שיא) בתדר הזה. המפה הזו חיונית להבנת השינויים בפלט הרטט בטווח התדרים הנתמך, ולהגדרת PWLE API הבסיסי.

בתרשים הבא מוצגת דוגמה ל-FOAM של אקטואטור רטט טיפוסי, עם מתח קלט מוגבל סביב תדר הרטט כדי להגן על המנוע:

איור 1. דוגמה ל-FOAM למפעיל רטט טיפוסי.

ל-FOAM יש שלוש מטרות עיקריות:

• הגדרת טווח התדרים המלא: ה-FOAM מגדיר את טווח התדרים המלא של המכשיר על ידי ציון תדירות הרטט המינימלית והמקסימלית הנתמכות.
• הגדרת הערכים של העוצמה והחדות: ה-API הבסיסי של PWLE פועל לפי סולם תפיסת האדם של עוצמה וחדות, שממופים לאחר מכן לפרמטרים של תדר ואמפליטודה של החומרה באמצעות ערכי האצה של הפלט ב-FOAM. המיפוי הזה עוזר להבטיח שהאפקטים החזותיים ישוחזרו בהתאם ליכולות החומרה. טווח החדות מוגדר לפי הסף המינימלי שניתן לזיהוי, והוא תואם לתדרים שבהם המכשיר יכול ליצור אפקטים הקטפטיים שהמשתמשים יכולים לחוש. המסגרת ממפה את ערכי העוצמה לאמפליטודה על סמך האצה היעד של הפלט בתדר שנבחר. כך אפשר לוודא שמגיעים לרמת העוצמה שנבחרה בלי לחרוג מהיכולות של המכשיר.
• חשיפת יכולות החומרה: ה-FOAM מוצג למפתחים ב-VibratorFrequencyProfile, ומספק את קבוצת הנתונים המלאה של תדירות הפלט של האצה, שמפרטת חלק מהיכולות החזותיות של המכשיר. הנתונים האלה מאפשרים למפתחים שמשתמשים ב-PWLE API המתקדם ליצור אפקטים מותאמים אישית של רטט, מעבר לטווח הבסיסי של העוצמה והחדות שמוגדרים במסגרת.

FOAM ו-PWLE API בסיסי

ל-FOAM יש תפקיד חיוני בעיצוב ההשפעות של הרטט. הוא משמש לחישוב טווח החדות של ממשק ה-API הבסיסי של האריזה, כדי לוודא שהמשתמשים יוכלו לחוש את הרטט. הטווח הזה תואם לתדרים שבהם האצה הפלט היא לפחות 10 dB מעל סף הזיהוי של תפיסת האדם (כלומר, הרמה המינימלית שניתן לזהות) לכל תדר. כך תוכלו לוודא שהרטט חזק מספיק כדי להרגיש אותו.

בנוסף, המסגרת משתמשת בנתוני FOAM כדי למפות את ערכי העוצמה והחדות שמשמשים ב-PWLE API הבסיסי לערכי האמפליטודה והתדר התואמים. המיפוי הזה עוזר ליצור משוב מישוש (haptic) שניתן לזהות במכשירים שונים.

בדיקות VTS נועדו לוודא שלמכשירים שתומכים באפקטים של מעטפת יש טווח תדרים לא ריק שיוצר רטט שניתן לחוש. כך אפשר להבטיח שהמכשיר יוכל לייצר רטט בעוצמה מספקת כדי שהמשתמשים יוכלו לחוש אותו בבירור.

FOAM ו-PWLE API מתקדם

VibratorFrequencyProfile חושף את FOAM למפתחים עם המידע הבא:

• טווח תדרים: מפתחים יכולים לאחזר את התדרים המינימלי והמקסימלי הנתמכים במכשיר, ב-Hz, באמצעות getMinFrequencyHz ו-getMaxFrequencyHz, בהתאמה.
• האצהרת הפלט המקסימלית: האצהרת הפלט המקסימלית (ב-G) שאפשר להשיג במכשיר זמינה דרך getMaxOutputAccelerationGs.
• מיפוי של תדירות להאצה של פלט: getFrequenciesOutputAcceleration מספק את המיפוי של תדירות להאצה של פלט כפי שהוא מיושם ב-HAL.

מפתחים יכולים להשתמש במידע הזה כשיוצרים אפקטים של מעטפות באמצעות PWLE API המתקדם. לדוגמה, כשמציינים תאוצה של פלט (ב-G), צריך לנרמל אותה לערך בטווח [0.0, 1.0], ביחס לתאוצת הפלט המקסימלית של המכשיר.

באמצעות ממשק ה-API המתקדם של PWLE, המפתחים יכולים להשתמש בכל טווח התדרים, ולכן חשוב מאוד שנתוני ה-FOAM שסופקו יהיו בטוחים לוויברטור ולא יחרגו מהיכולות שלו.

סף לזיהוי על ידי אדם

סף הגילוי של תפיסת האדם מתייחס לתאוצה המינימלית של רטט שאדם יכול לזהות באופן מהימן. רמת הרטט משתנה בהתאם לתדירות הרטט.

בתרשים הבא מוצג סף הזיהוי של תפיסת המגע האנושית¹, בחיזוקים, כפונקציה של תדירות זמנית:

איור 2. הסף לזיהוי של תפיסת המגע האנושית.

כדי שהמשתמשים יוכלו לחוש את האפקטים החזותיים באופן עקבי, בדיקות VTS מאמתות שמכשירים עם יכולות של עטיפה (envelope) כוללים טווח תדרים שיכול ליצור אמפליטודות של רטט שחורגות מסף הזיהוי של התפיסה האנושית ב-10 dB.

עוצמת הרטט הנתפסת לעומת אמפליטודה של תאוצת הרטט

התפיסה האנושית של עוצמת הרטט (מדד תפיסת) לא עולה באופן לינארי עם אמפליטודת הרטט (פרמטר פיזי). ב-PWLE API מוגדרת הנחת היסוד שלפיה כשמעצב או מפתח חושבים על שינויים בעוצמת הרטט, הם מצפים שהעוצמה הנתפסת תעמוד בקריטריונים של PWLE. עוצמה נתפסת מאופיינת ברמת החישה (SL), שמוגדר בדציבלים מעל סף הזיהוי באותה תדירות. לכן, ניתן לחשב את אמפליטודת האצה של הרטט (ב-G שיא) באופן הבא:

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

כאשר עוצמת האות ב-dB היא הסכום של SL וסף הזיהוי (הערך לאורך הציר האנכי בתרשים הבא) בתדר מסוים.

כך, ממשק ה-API של PWLE מבטיח שהעוצמה הנתפסת תשתנה באופן לינארי בין זוגות של נקודות בקרה עוקבות.

בתרשים הבא מוצגים רמות האצה של רטט² ברמות 10, 20, 30, 40 ו-50 dB SL, יחד עם סף הזיהוי של תפיסת המגע האנושית (0 dB SL), כפונקציה של תדירות זמנית.

איור 3. רמות האצה של הרטט.

קביעת עקומת ההאצה של התדירות לתפוקה המקסימלית

בקטע הזה מפורטות הנחיות כלליות לקבלת עקומת התדירות של האצה מקסימלית של הפלט מהמכשיר, שבה משתמשים כדי ליצור את נתוני FOAM.

קבלת עקומת המתח המקסימלי (V)

V הוא המתח המקסימלי שאפשר להחיל בבטחה על הרטט במהלך טווח תדרי הפעולה שלו. כך מוודאים שהוויברטור פועל במגבלות בטוחות, מונעים נזק וממקסמים את תפוקת הרטט.

אם החומרה כוללת תכונה של הגבלת מתח, אפשר להשתמש בה כדי למדוד ישירות את המתח המקסימלי שניתן להשיג בטווח התדרים הנתמך.

חישוב האצה מקסימלית (M)

M היא האצה מקסימלית, שאפשר לחשב באמצעות שיטות שונות. בקטע הזה מוצגת שיטה אחת למכשירים שמשתמשים במפעילים לינאריים בתהודה (LRA).

בשיטה הזו מתבצעת המרה של המתח המרבי שמוחל בתדר נתון לערך תאוצה מקסימלי תואם, שמוצג ב-G שיא.

המשוואה המרכזית שמשמשת להמרה הזו היא:

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

איפה:

Vsys: רמת המתח בפועל שחלה על המפעיל החשמלי של האפקט הרטט

BLsys: המכפלה של עוצמת השדה המגנטי (B) ואורך המוליך (L) של מנוע הרטט

Loc_coeff: מקדם מיקום להמרת האצה ברמת המודול לאצה ברמת הטלפון

Rsys: התנגדות חשמלית של סליל מנוע הרטט

MPhone: המסה של המכשיר (למשל, טלפון)

w: תדירות זוויתית (רדיאנים לשנייה) של אות ההנעה, מחושבת כך:

\(w = 2 \pi f\)

Psys_abs: תגובת המשרעת של מערכת מסה, דחיסה וקפיץ מסדר שני, שמחושבת לפי הנוסחה:

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

Wnsys: התדירות הטבעית של מערכת הרטט

Qsys: גורם האיכות של מערכת הרטט

הערך Loc_coeff הוא היחס בין האצה שנמדדת ברמת הטלפון לאצה שנמדדת ברמת המודול. היחס הזה משמש להמרת קריאות תאוצה ברמת המודול לקריאות תאוצה מקבילות ברמת הטלפון. ברמת הטלפון, בגלל האצה הזוויתית של תנועת המודול, האצה מתעצמת, והמכונה הזו מביאה בחשבון את סוג ההשפעה הזה. הערך מחושב כך:

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

לדוגמה, אם האצה של המודול היא 1g והאצה של הטלפון היא 2.5g, אז Loc_coeff = 2.5. המשמעות היא שמדובר בהגברה פי 2.5.

מסגרת Android מקבלת תדר ביחידת הרץ, ולכן ה-HAL צריך להמיר את יחידת התדר מרדיאנים לשנייה להרץ כשיוצרים את נתוני FOAM.

יצירת העקומה FOAM

משלבים את עקומת המתח המקסימלי (V) ואת חישוב ההאצה (M) כדי לקבוע את עקומת FOAM:

• לכל תדר (f) בטווח הרצוי, מחפשים את המתח המקסימלי התואם V(f) מתוך עקומת המתח המקסימלי.
• מחשבים את האצה המקסימלית בתדירות הזו באמצעות המשוואה שלמעלה, ומחליפים את Vsys ב-V(f) ואת w ב-f התואם. כך תקבלו את M(V(f), f).
• האצה מחושבת זו היא הערך של FOAM(f).

חשיפת הנתונים של FOAM

אחרי יצירת העקומה של FOAM, ה-HAL מייצג את העקומה כרשימה של אובייקטים מסוג FrequencyAccelerationMapEntry. כל רשומה מגדירה נקודה במיפוי, עם תדירות (בהרץ) והאצה מקסימלית תואמת של הפלט (ב-G שיא).

אין דרישות מחמירות לגבי הרזולוציה של FOAM, אבל מומלץ להגדיר עקומות עם שיא מקסימלי אחד. רק הפסגה הראשונה משמשת ב-Envelope API הבסיסי למיפוי של אפקטים של רטט. כדי לשפר את הדיוק של הבינוי הליניארי בזמן קביעה של ערכי תאוצה ביניים, מומלץ להגדיר רזולוציה של תדר גבוה סביב השיא. לדוגמה, אפשר להשתמש בצעדים של 1Hz בטווח של +/- 10Hz מתדירות השיא.

היכולות והמגבלות של המכשיר

בגרסה 16 ואילך של Android, כדי לעזור למפתחים לבצע אופטימיזציה של האפקטים של PWLE ולהבטיח תאימות במכשירים שונים, מערכת Android כוללת ממשקי HAL API לשליחת שאילתות לגבי יכולות ה-PWLE של המכשיר. השיטות האלה מספקות מידע על המגבלות של המכשיר, כמו משך הזמן המינימלי או המקסימלי של רכיב פרימיטיבי של PWLE ומספר הרכיבים הפרימיטיביים שמותר לכלול בהרכבה של PWLE.

ממשקי ה-API של HAL כוללים:

• CAP_COMPOSE_PWLE_EFFECTS_V2: הפונקציה IVibrator.getCapabilities מחזירה את הערך הזה כשהמכשיר תומך בתכונה הזו.
• getFrequencyToOutputAccelerationMap: אחזור נתוני FOAM.
• getPwleV2PrimitiveDurationMinMillis: אחזור משך הזמן המינימלי שמותר לכל PWLE פרימיטיבי באלפיות שנייה.
• getPwleV2PrimitiveDurationMaxMillis: אחזור משך הזמן המקסימלי שמותר לכל PWLE פרימיטיבי באלפיות שנייה.
• getPwleV2CompositionSizeMax: אחזור המספר המקסימלי של פרימטיבים של PWLE שנתמכים ב-IVibrator.composePwleV2.

המידע הזה מוצג למפתחים כדי לאפשר להם להתאים אישית את האפקטים ליכולות הספציפיות של מכשיר היעד, במיוחד כשמשתמשים ב-PWLE API המתקדם.

ה-framework משתמש בממשקי ה-API האלה גם כשמפעילים אפקטים שנוצרו באמצעות ה-API הבסיסי. אם אפקט חורג מהמגבלות של המכשיר (לדוגמה, יותר מדי נקודות PWLE או משך זמן ארוך מהמקסימום), המסגרת תשנה את האפקט באופן אוטומטי כך שיתאים לגבולות המותרים. בתהליך ההתאמה הזה אנחנו מנסים לשמור על הכוונה המקורית והתחושה המקורית של העיצוב ככל האפשר.