Implementa efectos de sobre lineal por partes

Los efectos de envolvente lineal por tramos (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 táctil más enriquecida y dinámica.

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

• API de PWLE básica: Es simple, pero tiene limitaciones. Es ideal para comenzar rápidamente. Está disponible en BasicEnvelopeBuilder.
• API de PWLE avanzada: Ofrece más control y flexibilidad, requiere conocimientos sobre la respuesta táctil y cierta familiaridad con el hardware. Está disponible en WaveformEnvelopeBuilder.

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

• Frecuencia de resonancia: Proporciona la frecuencia de resonancia del actuador.
• Asignación de frecuencia a 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.
• Componer PWLE: Reproduce una vibración definida por una PWLE de la forma de onda de vibración.

Nota: Aclaración de la terminología: En esta página, se usan amplitud y frecuencia para las mediciones físicas, y se usan intensidad y nitidez para los parámetros perceptuales.

API de PWLE básica

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 de PWLE básica, 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 lograr el dispositivo.
• El valor de nitidez en el rango de [0, 1] representa la nitidez 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.
• La 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.

Nota: La intensidad percibida de la vibración no se asigna de forma lineal a la aceleración de salida de la vibración. El framework de Android traduce el parámetro de envolvente de intensidad a la amplitud de la vibración, teniendo en cuenta la ley de potencia que rige la relación entre la intensidad percibida de la vibración y la amplitud de la aceleración de la vibración. Luego, esta amplitud traducida se envía a la implementación de hardware.

A continuación, se muestra un ejemplo de forma de onda que aumenta la intensidad de un tono bajo a una vibración de tono alto de 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 táctil fluida y sin interrupciones, 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 táctil del usuario.

Para garantizar la representació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 20 ms entre los puntos de PWLE y al menos 16 puntos para los efectos de PWLE. Los requisitos se aplican mediante pruebas de VTS, lo que ayuda a garantizar efectos de PWLE confiables en los dispositivos Android.

API de PWLE avanzada

Los desarrolladores con conocimientos avanzados en respuesta táctil pueden definir efectos de PWLE con estos criterios:

• El valor de amplitud en el rango de [0, 1] representa la intensidad que se puede lograr a una frecuencia determinada, según lo determinado por 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 a la frecuencia determinada.
• La frecuencia se especifica directamente en Hertz.
• 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 forma de onda que aumenta un vibrador de apagado a amplitud completa a 120 Hz durante 100 ms, mantiene ese estado durante 200 ms y, luego, vuelve a disminuir 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, pero 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 la FOAM del dispositivo. Si los valores superan estos límites, el dispositivo no reproduce ninguna vibración.

Asignación de frecuencia a aceleración de salida (FOAM)

La representación precisa de las capacidades de frecuencia a aceleración de salida de un dispositivo es esencial para admitir las APIs de PWLE. 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 una asignación de frecuencia a aceleración de salida (FOAM). La FOAM es una estructura de datos generada por el HAL que asigna la frecuencia de vibración (en Hertz) a la aceleración de salida máxima que se puede lograr del actuador (en G pico) a esa frecuencia. Este mapa es fundamental para comprender cómo varía la salida de vibración para el rango de frecuencia admitido y para definir la API de PWLE básica.

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

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

La FOAM tiene tres propósitos clave:

• Definir el rango de frecuencia completo: La FOAM define el rango de frecuencia completo del dispositivo especificando las frecuencias de vibración mínima y máxima admitidas.
• 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 mediante los valores de aceleración de salida en la FOAM. Esta asignación ayuda a garantizar que los efectos táctiles se representen según las capacidades del hardware. El rango de nitidez se define mediante el umbral mínimo perceptible y corresponde a las frecuencias en las que el dispositivo puede producir efectos táctiles 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 sin exceder las capacidades del dispositivo.
• Exponer las capacidades de hardware: La FOAM se expone a los desarrolladores en VibratorFrequencyProfile, lo que proporciona el conjunto de datos completo de frecuencia a aceleración de salida que detalla algunas de las capacidades táctiles del dispositivo. Estos datos permiten a los desarrolladores que usan la API de PWLE avanzada crear efectos de vibración personalizados que van más allá de los rangos básicos de intensidad y nitidez definidos por el framework.

FOAM y API de PWLE básica

La FOAM desempeña un papel fundamental en la configuración de los efectos de vibración. Se usa para calcular el rango de nitidez de la API de envolvente básica, lo que garantiza que las vibraciones sean perceptibles para el usuario. Este rango corresponde a las frecuencias desde donde la aceleración de salida alcanza por primera vez 10 dB por encima del umbral de detección de la percepción humana (es decir, el nivel mínimo perceptible) hasta donde la aceleración de salida está por encima de ese umbral. Este rango debe incluir la frecuencia de resonancia del actuador.

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 correspondientes de amplitud y frecuencia. Esta asignación ayuda a producir una respuesta táctil perceptible en diferentes dispositivos.

Las pruebas de VTS están en su lugar para garantizar que los dispositivos que admiten efectos de envolvente tengan un rango de frecuencia no vacío que produzca vibraciones perceptibles y que el rango contenga la frecuencia de resonancia del actuador. Esto ayuda a garantizar que el dispositivo pueda producir vibraciones con la intensidad suficiente para que los usuarios las sientan con claridad.

FOAM y API de PWLE avanzada

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

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

Los desarrolladores pueden usar esta información cuando crean efectos de envolvente con la API de PWLE avanzada. Por ejemplo, cuando especifican una aceleración de salida (en G), deben normalizarla 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 se refiere a la aceleración mínima de una vibración que una persona puede detectar de manera confiable. Este nivel varía según la frecuencia de vibración.

El siguiente diagrama muestra el umbral de detección de la percepción táctil humana¹, en aceleración, como una función de la frecuencia temporal:

Figura 2: Umbral de detección de la percepción táctil humana

Para que los usuarios puedan sentir los efectos táctiles de manera coherente, 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 percibida de la vibración en comparación con la amplitud de la aceleración de la vibración

La percepción humana de la intensidad de la vibración (una medida de percepción) no crece 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 dB por encima del umbral de detección en la misma frecuencia. Por lo tanto, la amplitud de la aceleración de la vibración (en G pico) se puede calcular de la siguiente manera:

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

En este formato, la amplitud dB es la suma de SL y el umbral de detección (el valor a lo largo de la ordenada en el siguiente diagrama) en una frecuencia determinada.

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 diagrama muestra los niveles de aceleración de la vibración² en 10, 20, 30, 40 y 50 dB SL, junto con el umbral de detección de la percepción táctil humana (0 dB SL), como una función de la frecuencia temporal.

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

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

En esta sección, se proporciona una guía general para obtener la curva de frecuencia a aceleración de salida máxima del dispositivo, que usas 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 los límites seguros, lo que evita daños y maximiza la salida de vibración.

**Precaución:** Existen diferentes métodos para determinar esta curva, pero es fundamental garantizar que los voltajes medidos estén dentro del rango de funcionamiento seguro del hardware para evitar daños.

Si el hardware incluye una función de limitación de voltaje, úsala para medir directamente el voltaje máximo que se puede lograr 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áxima 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 táctil

BLsys: Producto de la intensidad del campo magnético (B) y la longitud del conductor (L) de l 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 de la aceleración medida a nivel del teléfono con 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 aceleración 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 V(f) en la curva de voltaje máximo.
• Calcula la aceleración máxima a esa frecuencia con la ecuación anterior, sustituyendo V(f) por Vsys y la f correspondiente por w. Esto te da M(V(f), f).
• Esta aceleración calculada es tu valor FOAM(f).

Expón los datos de FOAM

Una vez que se genera 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 aceleración de salida máxima correspondiente (en G pico).

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 de la frecuencia con la aceleración de salida máxima. Por ejemplo, usa pasos de 1 Hz dentro del rango de +/- 10 Hz de esta frecuencia.

Capacidades 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 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: La devuelve IVibrator.getCapabilities 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 PWLE admitidas por IVibrator.composePwleV2.

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

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

---

1. Los datos del umbral se convierten del umbral de desplazamiento en la Figura 1 de Bolanowski Jr., S. J., et al. "Four channels mediate the mechanical aspects of touch." Journal of the Acoustical Society of America 84(5): 1680-1694 (1988). En este instructivo en línea, se explica la conversión entre la amplitud de aceleración y la amplitud de desplazamiento. ↩

2. Los datos se estiman a partir de la Figura 8 en Verrillo, R. T., et al. "Sensation magnitude of vibrotactile stimuli." Perception &Psychophysics 6: 366-372 (1969). ↩