Implementa efectos de sobre lineal por partes

Los efectos de envolvente lineal por partes (PWLE) son secuencias de puntos que definen la frecuencia y la aceleración de la vibración a lo largo del tiempo. Las PWLE ofrecen una respuesta háptica más rica y dinámica.

Android 16 y versiones posteriores proporcionan dos APIs para desarrolladores de apps que ayudan a crear efectos de PWLE:

• API básica de PWLE: Es simple, pero tiene limitaciones. Es una buena opción para comenzar rápidamente. Está disponible en BasicEnvelopeBuilder.
• API de PWLE avanzada: Más control y flexibilidad; requiere conocimientos sobre hápticos y cierta familiaridad con el hardware. Disponible en WaveformEnvelopeBuilder.

Para admitir estas APIs, los dispositivos deben implementar las siguientes APIs de HAL:

• Asignación de frecuencia para la aceleración de salida (FOAM): Proporciona una asignación de la frecuencia de vibración a la aceleración de salida máxima que se puede lograr para el dispositivo.
• Compose PWLE: Reproduce una vibración definida por una PWLE de la forma de onda de vibración.

API básica de PWLE

Para crear efectos de PWLE de forma rápida sin profundizar en el hardware ni en los matices de la percepción humana, los desarrolladores pueden usar la API básica de PWLE, que se define con estos parámetros:

• El valor de intensidad en el rango de [0, 1] representa la intensidad percibida de la vibración. Por ejemplo, un valor de 0.5 se percibe como la mitad de la intensidad máxima global que puede alcanzar el dispositivo.
• El valor de nitidez en el rango de [0, 1] representa la definición de la vibración. Los valores más bajos se traducen en vibraciones más suaves, mientras que los valores más altos crean una sensación más nítida.
• Duración es el tiempo que se tarda en pasar del último punto de PWLE (es decir, el par de intensidad y nitidez) al nuevo, en milisegundos.

A continuación, se muestra un ejemplo de forma de onda que aumenta la intensidad de una vibración de baja frecuencia a una de alta frecuencia y máxima intensidad durante 500 ms y, luego, disminuye a 0 (apagado) durante 100 ms:

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

Restricciones

Para crear una experiencia háptica fluida y sin inconvenientes, los efectos de PWLE deben comenzar y terminar con una intensidad de 0.0. La API aplica esto fijando la intensidad inicial en 0 y lanza una excepción si la intensidad final no es 0. Esta restricción evita efectos dinámicos no deseados en las vibraciones debido a discontinuidades en la amplitud que pueden afectar negativamente la percepción háptica del usuario.

Para garantizar una renderización coherente del efecto de PWLE en todo el ecosistema de Android, el framework requiere que los dispositivos que admiten esta función puedan controlar una duración mínima de 10 ms entre los puntos de PWLE y, al menos, 16 puntos para los efectos de PWLE. Los VTS tests aplican estos requisitos, lo que ayuda a garantizar efectos de PWLE confiables en todos los dispositivos Android.

API de PWLE avanzada

Los desarrolladores con conocimientos avanzados en hápticos pueden definir efectos PWLE con los siguientes criterios:

• El valor de amplitud en el rango de [0, 1] representa la intensidad alcanzable en una frecuencia determinada, según lo determina la FOAM del dispositivo. Por ejemplo, un valor de 0.5 genera la mitad de la aceleración de salida máxima que se puede lograr con la frecuencia determinada.
• La frecuencia se especifica directamente en hercios.
• La duración es el tiempo que se tarda en pasar del último punto de PWLE al nuevo, en milisegundos.

A continuación, se muestra un ejemplo de una forma de onda que aumenta la intensidad de un vibrador de apagado a amplitud completa a 120 Hz durante 100 ms, mantiene ese estado durante 200 ms y, luego, disminuye la intensidad durante 100 ms:

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

Restricciones

El framework no modifica los valores de frecuencia y amplitud solicitados que proporciona el desarrollador, sino que agrega un punto de partida de amplitud 0 para garantizar una transición fluida.

Los desarrolladores son responsables de garantizar que la frecuencia especificada en sus efectos de PWLE se encuentre dentro del rango admitido del dispositivo, según lo define el FOAM del dispositivo. Si los valores superan estos límites, el dispositivo no reproducirá ninguna vibración.

Frecuencia para generar la asignación de aceleración (FOAM)

Para admitir las APIs de PWLE, es fundamental que se represente con precisión la frecuencia de las capacidades de salida de aceleración de un dispositivo. En esta sección, se detalla la importancia de estos datos, cómo los usan las APIs de PWLE y el proceso para generarlos.

Comprende la asignación

Los dispositivos que admiten efectos de PWLE deben proporcionar un mapa de aceleración de salida de frecuencia (FOAM). El FOAM es una estructura de datos que genera el HAL y que asigna la frecuencia de vibración (en hercios) a la aceleración de salida máxima alcanzable del actuador (en G pico) en esa frecuencia. Este mapa es fundamental para comprender cómo varía la salida de vibración en el rango de frecuencia admitido y para definir la API básica de PWLE.

En el siguiente diagrama, se muestra un ejemplo de un FOAM para un actuador resonante típico, con el voltaje de entrada limitado alrededor de la frecuencia resonante para proteger el motor:

Figura 1: Ejemplo de un FOAM para un actuador resonante típico.

El FOAM cumple tres propósitos clave:

• Definición del rango de frecuencia completo: El FOAM define el rango de frecuencia completo del dispositivo especificando las frecuencias de vibración mínima y máxima admitidas.
• Cómo definir los valores de intensidad y nitidez: La API de PWLE básica opera en una escala de percepción humana para la intensidad y la nitidez, que luego se asignan a los parámetros de frecuencia y amplitud del hardware con los valores de aceleración de salida en el FOAM. Este mapeo ayuda a garantizar que los efectos hápticos se rendericen según las capacidades del hardware. El rango de nitidez se define por el umbral mínimo perceptible y corresponde a las frecuencias en las que el dispositivo puede producir efectos hápticos que los usuarios pueden sentir. El framework asigna los valores de intensidad a la amplitud según la aceleración de salida objetivo en la frecuencia seleccionada. Esto ayuda a garantizar que se alcance el nivel de intensidad seleccionado y que se mantenga dentro de las capacidades del dispositivo.
• Exposición de las capacidades de hardware: El FOAM se expone a los desarrolladores en VibratorFrequencyProfile, lo que proporciona el conjunto de datos completo de aceleración de salida de frecuencia que detalla algunas de las capacidades hápticas del dispositivo. Estos datos permiten a los desarrolladores que usan la API avanzada de PWLE crear efectos de vibración personalizados que van más allá de los rangos básicos de intensidad y nitidez definidos por el framework.

API básica de FOAM y PWLE

La FOAM cumple un rol fundamental en la definición de los efectos de vibración. Se usa para calcular el rango de nitidez de la API de sobre básico, lo que garantiza que las vibraciones sean perceptibles para el usuario. Este rango corresponde a las frecuencias en las que la aceleración de salida no es inferior a 10 dB por encima del umbral de detección de la percepción humana (es decir, el nivel mínimo perceptible) para cada frecuencia. Esto garantiza que las vibraciones sean lo suficientemente fuertes como para sentirse.

Además, el framework usa los datos de FOAM para asignar los valores de intensidad y nitidez que se usan en la API de PWLE básica a sus valores de amplitud y frecuencia correspondientes. Esta asignación ayuda a producir comentarios hápticos perceptibles en diferentes dispositivos.

Las pruebas de VTS garantizan que los dispositivos que admiten efectos de envolvente tengan un rango de frecuencia no vacío que produzca vibraciones perceptibles. Esto ayuda a garantizar que el dispositivo pueda producir vibraciones con la intensidad suficiente para que los usuarios las sientan con claridad.

API de FOAM y PWLE avanzada

VibratorFrequencyProfile expone FOAM a los desarrolladores con la siguiente información:

• Rango de frecuencia: Los desarrolladores pueden recuperar las frecuencias mínima y máxima admitidas del dispositivo, en hercios, con getMinFrequencyHz y getMaxFrequencyHz, respectivamente.
• Aceleración máxima de salida: La aceleración máxima de salida que puede alcanzar el dispositivo (en G) está disponible a través de getMaxOutputAccelerationGs.
• Asignación de la frecuencia a la aceleración de salida: getFrequenciesOutputAcceleration proporciona la asignación de la frecuencia a la aceleración de salida tal como se implementa en el HAL.

Los desarrolladores pueden usar esta información cuando creen efectos de envolvente con la API avanzada de PWLE. Por ejemplo, cuando se especifica una aceleración de salida (en G), se debe normalizar a un valor dentro del rango [0.0, 1.0], en relación con la aceleración de salida máxima del dispositivo.

Con la API de PWLE avanzada, los desarrolladores pueden usar todo el rango de frecuencia, por lo que es fundamental que los datos de FOAM proporcionados sean seguros para el vibrador y no excedan sus capacidades.

Umbral de detección de la percepción humana

El umbral de detección de la percepción humana hace referencia a la aceleración mínima de una vibración que una persona puede detectar de forma confiable. Este nivel varía según la frecuencia de vibración.

El siguiente gráfico muestra el umbral de detección de la percepción háptica humana¹, en aceleración, como una función de la frecuencia temporal:

Figura 2: Es el umbral de detección de la percepción háptica humana.

Para que los usuarios puedan sentir los efectos hápticos de manera constante, las pruebas de VTS validan que los dispositivos con capacidades de envolvente tengan un rango de frecuencia que pueda producir amplitudes de vibración que superen el umbral de detección de la percepción humana en 10 dB.

Intensidad de vibración percibida en comparación con la amplitud de aceleración de la vibración

La percepción humana de la intensidad de la vibración (una medida de percepción) no aumenta de forma lineal con la amplitud de la vibración (un parámetro físico). La API de PWLE supone que, cuando un diseñador o desarrollador piensa en los cambios en la intensidad de la vibración, espera que la intensidad percibida siga una PWLE. La intensidad percibida se caracteriza por el nivel de sensación (SL), que se define como los dB por encima del umbral de detección en la misma frecuencia. Por lo tanto, la amplitud de aceleración de la vibración (en G pico) se puede calcular de la siguiente manera:

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

Aquí, los dB de amplitud son la suma del nivel de sonido y el umbral de detección (el valor a lo largo de la ordenada en el siguiente gráfico) en una frecuencia en particular.

De esta manera, la API de PWLE garantiza que la intensidad percibida cambie de forma lineal entre pares sucesivos de puntos de control.

El siguiente gráfico muestra los niveles de aceleración de vibración² a 10, 20, 30, 40 y 50 dB SL, junto con el umbral de detección de la percepción háptica humana (0 dB SL), en función de la frecuencia temporal.

Figura 3: Niveles de aceleración de vibración

Determina la curva de aceleración de la frecuencia a la salida máxima

En esta sección, se proporciona un lineamiento general para obtener la curva de aceleración de salida máxima a frecuencia del dispositivo, que se usa para generar los datos de FOAM.

Obtén la curva de voltaje máximo (V)

V es el voltaje máximo que se puede aplicar de forma segura al vibrador en su rango de frecuencia de funcionamiento. Esto garantiza que el vibrador funcione dentro de límites seguros, lo que evita daños y maximiza la salida de vibración.

Si el hardware incluye una función de limitación de voltaje, úsala para medir directamente el voltaje máximo alcanzable en el rango de frecuencia admitido.

Calcula la aceleración máxima (M).

M es la aceleración máxima, que puedes calcular con varias metodologías. En esta sección, se muestra un método para dispositivos que usan actuadores resonantes lineales (LRA).

Este método convierte el voltaje máximo aplicado a una frecuencia determinada en un valor de aceleración máximo correspondiente, expresado en G pico.

La ecuación principal que se usa para esta conversión es la siguiente:

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

En la que:

Vsys: Nivel de voltaje real aplicado al actuador háptico

BLsys: Producto de la intensidad del campo magnético (B) y la longitud del conductor (L) del motor de vibración

Loc_coeff: Coeficiente de ubicación para convertir la aceleración a nivel del módulo en aceleración a nivel del teléfono

Rsys: Resistencia eléctrica de la bobina del motor de vibración

MPhone: Masa del dispositivo (por ejemplo, teléfono)

w: Frecuencia angular (radianes por segundo) de la señal de conducción, calculada de la siguiente manera:

\(w = 2 \pi f\)

Psys_abs: Respuesta de amplitud de un sistema de masa, amortiguador y resorte de segundo orden, calculada de la siguiente manera:

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

Wnsys: Frecuencia natural del sistema vibratorio

Qsys: Factor de calidad del sistema vibratorio

Loc_coeff es la proporción entre la aceleración medida a nivel del teléfono y la aceleración medida a nivel del módulo. Esta proporción se usa para convertir las lecturas de aceleración a nivel del módulo en lecturas de aceleración equivalentes a nivel del teléfono. A nivel del teléfono, debido a la aceleración angular del movimiento del módulo, la aceleración se amplifica, y este coeficiente tiene en cuenta ese tipo de efecto. Se calcula de la siguiente manera:

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

Por ejemplo, si la aceleración del módulo es de 1 g y la del teléfono es de 2.5 g, entonces Loc_coeff = 2.5. Esto indica una amplificación de 2.5 veces.

El framework de Android toma la frecuencia en la unidad de Hertz, por lo que el HAL debe convertir la unidad de frecuencia de radianes por segundo a Hertz cuando genera los datos de FOAM.

Genera la curva de FOAM

Combina la curva de voltaje máximo (V) y el cálculo de aceleración (M) para determinar la curva de FOAM:

• Para cada frecuencia (f) en el rango deseado, busca el voltaje máximo correspondiente V(f) en la curva de voltaje máximo.
• Calcula la aceleración máxima en esa frecuencia con la ecuación anterior, sustituyendo V(f) por Vsys y el f correspondiente por w. Esto te da M(V(f), f).
• Esta aceleración calculada es tu valor de FOAM(f).

Expón los datos de FOAM

Después de generar la curva de FOAM, el HAL representa la curva como una lista de objetos FrequencyAccelerationMapEntry. Cada entrada define un punto en la asignación, especificando una frecuencia (en Hertz) y su correspondiente aceleración máxima de salida (en G pico).

Si bien no hay requisitos estrictos para la resolución del FOAM, recomendamos definir curvas con un pico máximo. Solo se usa el primer pico en la API de envolvente básica para asignar los efectos de vibración. Para optimizar la precisión de la interpolación lineal cuando se determinan los valores de aceleración intermedios, recomendamos definir una resolución de frecuencia alta alrededor del pico. Por ejemplo, usa pasos de 1 Hz dentro del rango de +/- 10 Hz de la frecuencia máxima.

Funciones y limitaciones del dispositivo

En Android 16 y versiones posteriores, para ayudar a los desarrolladores a optimizar sus efectos de PWLE y garantizar la compatibilidad en todos los dispositivos, Android incluye APIs de HAL para consultar las capacidades de PWLE del dispositivo. Estos métodos proporcionan información sobre las limitaciones del dispositivo, como la duración mínima o máxima de la primitiva de PWLE y la cantidad de primitivas permitidas en una composición de PWLE.

Las APIs de HAL incluyen lo siguiente:

• CAP_COMPOSE_PWLE_EFFECTS_V2: IVibrator.getCapabilities devuelve este valor cuando el dispositivo admite esta función.
• getFrequencyToOutputAccelerationMap: Recupera los datos de FOAM.
• getPwleV2PrimitiveDurationMinMillis: Recupera la duración mínima permitida para cualquier PWLE primitiva en milisegundos.
• getPwleV2PrimitiveDurationMaxMillis: Recupera la duración máxima permitida para cualquier PWLE primitiva en milisegundos.
• getPwleV2CompositionSizeMax: Recupera la cantidad máxima de primitivas de PWLE admitidas por IVibrator.composePwleV2.

Esta información se expone a los desarrolladores para que puedan adaptar sus efectos a las capacidades específicas del dispositivo de destino, en especial cuando usan la API avanzada de PWLE.

El framework también usa estas APIs cuando controla los efectos creados con la API básica. Si un efecto supera las limitaciones del dispositivo (por ejemplo, demasiados puntos de PWLE o una duración que supera el máximo), el framework ajusta automáticamente el efecto para que se ajuste a los límites permitidos. Este proceso de ajuste intenta conservar la intención y el estilo originales del diseño en la mayor medida posible.