Implementare effetti envelope lineari piecewise

Gli effetti dell'inviluppo lineare a tratti (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. Ideale per iniziare rapidamente. Disponibile all'indirizzo BasicEnvelopeBuilder.
• API PWLE avanzata: maggiore controllo e flessibilità, richiede conoscenze aptiche e una certa familiarità con l'hardware. Disponibile all'indirizzo WaveformEnvelopeBuilder.

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

• Mappatura della frequenza all'accelerazione di output (FOAM): fornisce una mappatura della frequenza di vibrazione all'accelerazione di output massima raggiungibile per il dispositivo.
• Componi PWLE:riproduce una vibrazione definita da una 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 la forza 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ù alti creano una sensazione più netta.
• Durata è il tempo necessario per passare dall'ultimo punto PWLE (ovvero la coppia intensità e nitidezza) al nuovo, in millisecondi.

Ecco un esempio di forma d'onda che aumenta l'intensità da un tono basso a una vibrazione di massima intensità a tono alto in 500 ms e poi diminuisce fino a 0 (spento) 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 aptica fluida e senza interruzioni, gli effetti PWLE devono iniziare e terminare con un'intensità pari a 0.0. L'API lo applica impostando l'intensità iniziale su 0 e genera un'eccezione se l'intensità finale non è 0. Questo vincolo impedisce effetti dinamici indesiderati nelle vibrazioni dovuti a discontinuità nell'ampiezza che possono influire negativamente sulla percezione aptica 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.

Advanced PWLE API

Gli sviluppatori con conoscenze avanzate in aptica possono definire gli effetti PWLE utilizzando questi criteri:

• Il valore Ampiezza nell'intervallo [0, 1] rappresenta la forza raggiungibile a una determinata frequenza, come determinato dalla funzione FOAM del dispositivo. Ad esempio, un valore pari a 0,5 genera la metà dell'accelerazione di output massima che può essere raggiunta alla frequenza specificata.
• La frequenza è specificata direttamente in Hertz.
• Durata è il tempo impiegato per passare dall'ultimo punto PWLE a quello nuovo, in millisecondi.

Ecco un esempio di forma d'onda che aumenta l'intensità di un vibratore da spento a piena ampiezza a 120 Hz in 100 ms, mantiene questo stato per 200 ms e poi diminuisce di nuovo 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 con 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 riproduce alcuna vibrazione.

Mappatura dell'accelerazione della frequenza di output (FOAM)

La rappresentazione accurata della frequenza di un dispositivo per l'output delle funzionalità di accelerazione è essenziale per supportare le API PWLE. Questa sezione descrive in dettaglio l'importanza di questi dati, come vengono utilizzati dalle API PWLE e il processo di generazione.

Comprendere la mappatura

I dispositivi che supportano gli effetti PWLE devono fornire una frequenza per l'output della mappa di accelerazione (FOAM). Il FOAM è una struttura di dati generata dall'HAL che mappa la frequenza di vibrazione (in Hertz) all'accelerazione di uscita massima raggiungibile dell'attuatore (in G di picco) a quella frequenza. Questa mappa è fondamentale per comprendere come varia l'output di vibrazione 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'intervallo di frequenza completo:il FOAM definisce l'intervallo di frequenza completo 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 mappate ai parametri di frequenza e ampiezza dell'hardware utilizzando i valori di accelerazione dell'output in FOAM. Questo mapping contribuisce a garantire che gli effetti aptici vengano 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 aptici che gli utenti possono sentire. Il framework mappa i valori di intensità in ampiezza in base all'accelerazione dell'output target alla frequenza selezionata. In questo modo, puoi assicurarti che il livello di intensità selezionato venga raggiunto rimanendo entro le capacità del dispositivo.
• Esposizione delle funzionalità hardware:il FOAM è esposto agli sviluppatori in VibratorFrequencyProfile, fornendo il set di dati completo di accelerazione da output a frequenza che descrive in dettaglio alcune delle funzionalità aptiche 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

FOAM svolge un ruolo fondamentale nel modellare gli effetti di vibrazione. Viene utilizzato per calcolare l'intervallo di nitidezza per l'API Envelope di base, garantendo che le vibrazioni siano percepibili dall'utente. Questo intervallo corrisponde alle frequenze in cui l'accelerazione in uscita non è inferiore a 10 dB al di sopra della soglia di rilevamento della percezione umana (ovvero il livello minimo percepibile) per ogni frequenza. In questo modo le vibrazioni sono 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 contribuisce a produrre un feedback aptico percepibile su diversi dispositivi.

I test VTS sono in atto per garantire che i dispositivi che supportano gli effetti di inviluppo abbiano una gamma di frequenze non vuota che produce vibrazioni percepibili. Ciò contribuisce a garantire che il dispositivo possa produrre vibrazioni con un'intensità sufficiente per essere chiaramente percepita dagli utenti.

API FOAM e PWLE avanzate

FOAM è esposto agli sviluppatori da VibratorFrequencyProfile con le seguenti informazioni:

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

Gli sviluppatori possono utilizzare queste informazioni quando creano effetti di busta con l'API PWLE avanzata. Ad esempio, quando si specifica un'accelerazione di output (in G), è necessario normalizzarla a un valore compreso nell'intervallo [0.0, 1.0], rispetto all'accelerazione di output 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 ne superino le capacità.

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 di vibrazione.

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

Figura 2. Soglia di rilevamento della percezione aptica umana.

Affinché gli utenti possano percepire in modo uniforme gli effetti aptici, i test VTS verificano che i dispositivi con funzionalità di inviluppo abbiano una gamma di frequenze in grado di produrre ampiezze di vibrazione che superano la 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 di percezione) non cresce in modo lineare con l'ampiezza della vibrazione (un parametro fisico). L'API PWLE presuppone che quando un designer o uno sviluppatore pensa alle modifiche all'intensità della vibrazione, si aspetta che l'intensità percepita segua una 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 delle vibrazioni (in G di picco) può essere calcolata come segue:

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

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

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

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

Figura 3. Livelli di accelerazione della vibrazione.

Determina la frequenza della curva di accelerazione dell'output massimo

Questa sezione fornisce una linea guida generale su come ottenere la curva di accelerazione di uscita massima dalla frequenza dal dispositivo, 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 di vibrazione.

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 con varie metodologie. Questa sezione mostra un metodo per i dispositivi che utilizzano attuatori risonanti lineari (LRA).

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

L'equazione principale 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 smartphone

Rsys: Resistenza elettrica della bobina del motore vibrazione

MPhone: Massa del dispositivo (ad esempio, smartphone)

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

\(w = 2 \pi f\)

Psys_abs: Risposta in ampiezza di un sistema di massa, smorzatore 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 di vibrazione

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 calcolato 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, allora Loc_coeff = 2,5. Ciò indica un'amplificazione di 2,5 volte.

Il framework Android accetta la frequenza in unità di Hertz, quindi l'HAL deve convertire l'unità di frequenza da radianti al secondo a 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 della tensione massima.
• Calcola l'accelerazione massima a quella frequenza utilizzando l'equazione sopra, sostituendo V(f) a Vsys e il valore f corrispondente a w. In questo modo, avrai M(V(f), f).
• Questa accelerazione calcolata è il valore di FOAM(f).

Esporre i dati FOAM

Una volta generata la curva FOAM, HAL la rappresenta come un elenco di oggetti FrequencyAccelerationMapEntry. Ogni voce definisce un punto nella mappatura, specificando una frequenza (in hertz) e la relativa accelerazione massima in uscita (in G di picco).

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

Funzionalità e limitazioni del dispositivo

Per Android 16 e versioni successive, per aiutare gli sviluppatori a ottimizzare gli effetti PWLE e garantire la compatibilità tra i dispositivi, Android include API HAL per interrogare le funzionalità PWLE del dispositivo. Questi metodi forniscono informazioni sulle limitazioni del dispositivo, come la durata minima o massima della primitiva 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 PWLE primitiva in millisecondi.
• getPwleV2PrimitiveDurationMaxMillis: recupera la durata massima consentita per qualsiasi PWLE primitiva 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 gli effetti in base alle funzionalità specifiche del dispositivo di destinazione, in particolare quando utilizzano l'API PWLE avanzata.

Il framework utilizza queste API anche per la gestione degli effetti creati con l'API di base. Se un effetto supera i limiti del dispositivo (ad esempio, troppi punti PWLE o una durata superiore al massimo), il framework lo regola automaticamente per rientrare nei limiti consentiti. Questa procedura di aggiustamento cerca di preservare il più possibile l'intento e l'aspetto originali del design.