Implementare effetti envelope lineari piecewise

Gli effetti envelope lineari frazionati (PWLE) sono sequenze di punti che definiscono la frequenza e l'accelerazione delle vibrazioni nel tempo. I PWLE offrono un feedback aptico più ricco e dinamico.

Android 16 e versioni successive forniscono due API per sviluppatori di app per contribuire a creare effetti PWLE:

• API PWLE di base: semplice, ma con limitazioni. Ottima soluzione per iniziare rapidamente. Questo articolo è disponibile all'indirizzo BasicEnvelopeBuilder.
• API PWLE avanzata: offre maggiore controllo e flessibilità, richiede conoscenza dell'aptica e una certa familiarità con l'hardware. Disponibile su WaveformEnvelopeBuilder.

Per supportare queste API, i dispositivi devono implementare le seguenti API HAL:

• Mappatura della frequenza all'accelerazione in uscita (FOAM): fornisce una mappatura della frequenza di vibrazione all'accelerazione in uscita massima raggiungibile per il dispositivo.
• Componi PWLE:riproduce una vibrazione definita da un PWLE della forma d'onda della vibrazione.

API PWLE di base

Per creare rapidamente effetti PWLE senza approfondire l'hardware o le sfumature della percezione umana, gli sviluppatori possono utilizzare l'API PWLE di base, definita utilizzando questi parametri:

• Il valore Intensità nell'intervallo [0, 1] rappresenta l'intensità percepita della vibrazione. Ad esempio, un valore di 0,5 viene percepito come la metà dell'intensità massima globale che può essere raggiunta dal dispositivo.
• Il valore Nitidezza compreso nell'intervallo [0, 1] rappresenta la nitidezza della vibrazione. Valori più bassi si traducono in vibrazioni più fluide, mentre valori più elevati creano una sensazione più acuta.
• La durata è il tempo necessario per passare dall'ultimo punto PWLE (ovvero la coppia di intensità e nitidezza) a quello nuovo, in millisecondi.

Ecco un esempio di forma d'onda che aumenta l'intensità da un tono basso a un tono alto con vibrazione di intensità massima in 500 ms e poi diminuisce fino a 0 (off) in 100 ms:

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

Vincoli

Per creare un'esperienza tattile fluida e senza interruzioni, gli effetti PWLE devono iniziare e terminare con un'intensità di 0,0. L'API applica questa regola fissando l'intensità iniziale su 0 e generando un'eccezione se l'intensità finale non è 0. Questo vincolo impedisce effetti dinamici indesiderati nelle vibrazioni a causa di discontinuità nell'ampiezza che possono influire negativamente sulla percezione tattile dell'utente.

Per garantire un rendering coerente dell'effetto PWLE nell'ecosistema Android, il framework richiede che i dispositivi che supportano questa funzionalità possano gestire una durata minima di 10 ms tra i punti PWLE e almeno 16 punti per gli effetti PWLE. Questi requisiti vengono applicati dai test VTS, contribuendo a garantire effetti PWLE affidabili su tutti i dispositivi Android.

API PWLE avanzata

Gli sviluppatori con conoscenze avanzate in materia di tecnologia aptica possono definire gli effetti PWLE utilizzando i seguenti criteri:

• Il valore Amplitude nell'intervallo [0, 1] rappresenta l'intensità conseguibile a una determinata frequenza, come stabilito dal FOAM del dispositivo. Ad esempio, un valore di 0,5 genera metà dell'accelerazione massima in uscita che può essere raggiunta alla frequenza specificata.
• La frequenza è specificata direttamente in Hertz.
• La durata è il tempo necessario per passare dall'ultimo punto PWLE a quello nuovo, in millisecondi.

Ecco un esempio di forma d'onda che aumenta gradualmente l'ampiezza di un vibratore da spento a massima a 120 Hz in 100 ms, mantiene questo stato per 200 ms e poi diminuisce gradualmente in 100 ms:

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

Vincoli

Il framework non modifica i valori di frequenza e ampiezza richiesti forniti dallo sviluppatore, ma aggiunge un punto di partenza di ampiezza 0 per garantire una transizione fluida.

Gli sviluppatori sono responsabili di garantire che la frequenza specificata negli effetti PWLE rientri nell'intervallo supportato dal dispositivo, come definito dal FOAM del dispositivo. Se i valori superano questi limiti, il dispositivo non emette vibrazioni.

Mappatura della frequenza all'accelerazione dell'output (FOAM)

La rappresentazione accurata delle funzionalità di accelerazione in uscita in base alla frequenza di un dispositivo è essenziale per supportare le API PWLE. Questa sezione descrive in dettaglio il significato di questi dati, come vengono utilizzati dalle API PWLE e il processo di generazione.

Informazioni sulla mappatura

I dispositivi che supportano gli effetti PWLE devono fornire una mappa di accelerazione in uscita (FOAM) in base alla frequenza. FOAM è una struttura di dati generata dall'HAL che mappa la frequenza di vibrazione (in Hertz) all'accelerazione in uscita massima (in G picco) raggiungibile dall'attuatore a quella frequenza. Questa mappa è fondamentale per comprendere in che modo l'output delle vibrazioni varia per l'intervallo di frequenza supportato e per definire l'API PWLE di base.

Il seguente grafico mostra un esempio di FOAM per un tipico attuatore risonante, con la tensione di ingresso limitata intorno alla frequenza di risonanza per proteggere il motore:

Figura 1. Esempio di FOAM per un tipico attuatore risonante.

Il FOAM ha tre scopi principali:

• Definizione dell'intera gamma di frequenza: il FOAM definisce l'intera gamma di frequenza del dispositivo specificando le frequenze di vibrazione minima e massima supportate.
• Definizione dei valori di intensità e nitidezza:l'API PWLE di base opera su una scala di percezione umana per intensità e nitidezza, che vengono poi mappati ai parametri di frequenza e ampiezza dell'hardware utilizzando i valori di accelerazione in uscita nel FOAM. Questa mappatura contribuisce a garantire che gli effetti di vibrazione siano visualizzati in base alle funzionalità hardware. L'intervallo di nitidezza è definito dalla soglia minima percepibile e corrisponde alle frequenze in cui il dispositivo può produrre effetti a livello tattile che gli utenti possono percepire. Il framework mappa i valori di intensità all'ampiezza in base all'accelerazione in uscita target alla frequenza selezionata. In questo modo, puoi assicurarti di raggiungere il livello di intensità selezionato rispettando le funzionalità del dispositivo.
• Esposizione delle funzionalità hardware: il FOAM è esposto agli sviluppatori in VibratorFrequencyProfile, fornendo il set di dati completo della frequenza di output dell'accelerazione che descrive alcune delle funzionalità di aptica del dispositivo. Questi dati consentono agli sviluppatori che utilizzano l'API PWLE avanzata di creare effetti di vibrazione personalizzati che vanno oltre gli intervalli di intensità e nitidezza di base definiti dal framework.

API FOAM e PWLE di base

Il FOAM svolge un ruolo fondamentale nella definizione degli effetti di vibrazione. Viene utilizzato per calcolare l'intervallo di nitidezza per l'API envelope di base, garantendo che le vibrazioni siano percepibili all'utente. Questo intervallo corrisponde alle frequenze in cui l'accelerazione in uscita è superiore a 10 dB rispetto alla soglia di rilevamento della percezione umana (ovvero il livello minimo percepibile) per ogni frequenza. In questo modo, le vibrazioni saranno abbastanza forti da essere percepite.

Inoltre, il framework utilizza i dati FOAM per mappare i valori di intensità e nitidezza utilizzati nell'API PWLE di base ai valori di ampiezza e frequenza corrispondenti. Questa mappatura consente di produrre un feedback aptico percepibile su diversi dispositivi.

I test VTS sono stati implementati per garantire che i dispositivi che supportano gli effetti envelope abbiano una gamma di frequenze non vuota che produca vibrazioni percettibili. In questo modo, il dispositivo può produrre vibrazioni con intensità sufficiente per essere percepite chiaramente dagli utenti.

API FOAM e PWLE avanzata

FOAM viene mostrato agli sviluppatori da VibratorFrequencyProfile con le seguenti informazioni:

• Intervallo di frequenza: gli sviluppatori possono recuperare le frequenze minime e massime supportate del dispositivo, in Hertz, utilizzando rispettivamente getMinFrequencyHz e getMaxFrequencyHz.
• Accelerazione massima in uscita: l'accelerazione massima in uscita (in G) raggiungibile dal dispositivo è disponibile tramite getMaxOutputAccelerationGs.
• Mappatura della frequenza all'accelerazione in uscita: getFrequenciesOutputAcceleration fornisce la mappatura della frequenza all'accelerazione in uscita come implementata nell'HAL.

Gli sviluppatori possono utilizzare queste informazioni per creare effetti envelope con l'API PWLE avanzata. Ad esempio, quando specificano un'accelerazione in uscita (in G), devono normalizzarla a un valore compreso nell'intervallo [0,0, 1,0] rispetto all'accelerazione in uscita massima del dispositivo.

Con l'API PWLE avanzata, gli sviluppatori possono utilizzare l'intera gamma di frequenze, quindi è fondamentale che i dati FOAM forniti siano sicuri per il vibratore e non superino le sue funzionalità.

Soglia di rilevamento della percezione umana

La soglia di rilevamento della percezione umana si riferisce all'accelerazione minima di una vibrazione che una persona può rilevare in modo affidabile. Questo livello varia in base alla frequenza della vibrazione.

Il seguente grafico mostra la soglia di rilevamento della percezione tattile umana¹, in accelerazione, in funzione della frequenza temporale:

Figura 2. Soglia di rilevamento della percezione tattile umana.

Affinché gli utenti possano sentire in modo coerente gli effetti aptico, i test VTS verificano che i dispositivi con funzionalità di envelope abbiano una gamma di frequenza che può produrre ampiezze di vibrazione superiori alla soglia di rilevamento della percezione umana di 10 dB.

Intensità della vibrazione percepita rispetto all'ampiezza dell'accelerazione della vibrazione

La percezione umana dell'intensità della vibrazione (una misura della percezione) non cresce linearmente con l'ampiezza della vibrazione (un parametro fisico). L'API PWLE presuppone che un designer o uno sviluppatore, quando pensa alle variazioni dell'intensità della vibrazione, si aspetti che l'intensità percepita segua una curva PWLE. L'intensità percepita è caratterizzata dal livello di sensazione (SL), definito come dB sopra la soglia di rilevamento alla stessa frequenza. Pertanto, l'ampiezza dell'accelerazione della vibrazione (in picco G) può essere calcolata come segue:

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

Dove l'ampiezza in dB è la somma di SL e della soglia di rilevamento (il valore sull'asse ordinate nel seguente grafico) a una determinata frequenza.

In questo modo, l'API PWLE garantisce che l'intensità percepita vari in modo lineare tra coppie successive di punti di controllo.

Il seguente grafico mostra i livelli di accelerazione della vibrazione² a 10, 20, 30, 40 e 50 dB SL, insieme alla soglia di rilevamento della percezione tattile umana (0 dB SL), in funzione della frequenza temporale.

Figura 3. Livelli di accelerazione della vibrazione.

Determina la curva di accelerazione della frequenza all'uscita massima

Questa sezione fornisce una linea guida generale su come ottenere dal dispositivo la curva di accelerazione della frequenza all'uscita massima, che utilizzi per generare i dati FOAM.

Ottieni la curva di tensione massima (V)

V è la tensione massima che può essere applicata in sicurezza al vibratore nell'intervallo di frequenza di funzionamento. In questo modo, il vibratore funziona entro limiti di sicurezza, evitando danni e massimizzando l'output delle vibrazioni.

Se l'hardware include una funzionalità di limitazione della tensione, utilizzala per misurare direttamente la tensione massima raggiungibile nell'intervallo di frequenza supportato.

Calcola l'accelerazione massima (M)

M è l'accelerazione massima, che puoi calcolare tramite varie metodiche. Questa sezione mostra un metodo per i dispositivi che utilizzano attuatori lineari risonanti (LRA).

Questo metodo converte la tensione massima applicata a una determinata frequenza in un valore di accelerazione massima corrispondente, espresso in G picco.

L'equazione di base utilizzata per questa conversione è:

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

Dove:

Vsys: livello di tensione effettivo applicato all'attuatore aptico

BLsys: prodotto dell'intensità del campo magnetico (B) e della lunghezza del conduttore (L) del motore di vibrazione

Loc_coeff: coefficiente di posizione per convertire l'accelerazione a livello di modulo in accelerazione a livello di telefono

Rsys: resistenza elettrica della bobina del motore di vibrazione

MPhone: massa del dispositivo (ad esempio, smartphone)

w: frequenza angolare (radianti al secondo) del segnale di azionamento, calcolata come segue:

\(w = 2 \pi f\)

Psys_abs: risposta in termini di ampiezza di un sistema di massa, ammortizzatore e molla di secondo ordine, calcolata come:

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

Wnsys: frequenza naturale del sistema vibrante

Qsys: fattore di qualità del sistema vibrante

Loc_coeff è il rapporto tra l'accelerazione misurata a livello di smartphone e l'accelerazione misurata a livello di modulo. Questo rapporto viene utilizzato per convertire le letture dell'accelerazione a livello di modulo in letture dell'accelerazione a livello di smartphone equivalenti. A livello di smartphone, a causa dell'accelerazione angolare del movimento del modulo, l'accelerazione viene amplificata e questo coefficiente tiene conto di questo tipo di effetto. Viene calcolata in questo modo:

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

Ad esempio, se l'accelerazione del modulo è 1 g e l'accelerazione dello smartphone è 2,5 g, Loc_coeff = 2,5. Ciò indica un'amplificazione di 2,5 volte.

Il framework Android prende la frequenza in unità di Hertz, quindi l'HAL deve convertire l'unità di frequenza da radianti al secondo in Hertz durante la generazione dei dati FOAM.

Genera la curva FOAM

Combina la curva di tensione massima (V) e il calcolo dell'accelerazione (M) per determinare la curva FOAM:

• Per ogni frequenza (f) nell'intervallo desiderato, trova la tensione massima V(f) corrispondente dalla curva di tensione massima.
• Calcola l'accelerazione massima a quella frequenza utilizzando l'equazione sopra, sostituendo V(f) per Vsys e il corrispondente f per w. In questo modo ottieni M(V(f), f).
• Questa accelerazione calcolata è il valore FOAM(f).

Esporre i dati FOAM

Dopo aver generato la curva FOAM, l'HAL la rappresenta come un elenco di oggetti FrequencyAccelerationMapEntry. Ogni voce definisce un punto nella mappatura, specificando una frequenza (in hertz) e l'accelerazione massima in uscita corrispondente (in G picco).

Sebbene non siano previsti requisiti rigorosi per la risoluzione del FOAM, consigliamo di definire curve con un picco massimo. Nell'API envelope di base viene utilizzato solo il primo picco per mappare gli effetti di vibrazione. Per ottimizzare la precisione dell'interpolazione lineare durante la determinazione dei valori di accelerazione intermedi, consigliamo di definire una risoluzione ad alta frequenza intorno al picco. Ad esempio, utilizza incrementi di 1 Hz nell'intervallo di +/- 10 Hz rispetto alla frequenza di picco.

Funzionalità e limitazioni del dispositivo

Per Android 16 e versioni successive, per aiutare gli sviluppatori a ottimizzare i propri effetti PWLE e garantire la compatibilità tra i dispositivi, Android include API HAL per eseguire query sulle funzionalità PWLE del dispositivo. Questi metodi forniscono informazioni sulle limitazioni del dispositivo, ad esempio la durata minima o massima delle primitive PWLE e il numero di primitive consentite in una composizione PWLE.

Le API HAL includono:

• CAP_COMPOSE_PWLE_EFFECTS_V2: viene restituito da IVibrator.getCapabilities quando il dispositivo supporta questa funzionalità.
• getFrequencyToOutputAccelerationMap: recupera i dati FOAM.
• getPwleV2PrimitiveDurationMinMillis: recupera la durata minima consentita per qualsiasi primitiva PWLE in millisecondi.
• getPwleV2PrimitiveDurationMaxMillis: recupera la durata massima consentita per qualsiasi primitiva PWLE in millisecondi.
• getPwleV2CompositionSizeMax: recupera il numero massimo di primitive PWLE supportate da IVibrator.composePwleV2.

Queste informazioni vengono esposte agli sviluppatori per consentire loro di personalizzare i propri effetti in base alle funzionalità specifiche del dispositivo di destinazione, in particolare quando viene utilizzata l'API PWLE avanzata.

Il framework utilizza queste API anche per gestire gli effetti creati con l'API di base. Se un effetto supera le limitazioni del dispositivo (ad esempio, troppi punti PWLE o una durata superiore al massimo), il framework regola automaticamente l'effetto in modo che rientri nei limiti consentiti. Questa procedura di aggiustamento tenta di mantenere il più possibile l'intento e l'atmosfera originali del design.