Implementa efectos de sobre lineal por partes

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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

Android 16 y versiones posteriores proporcionan dos APIs para desarrolladores de apps para ayudar 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 la tecnología táctil 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 a aceleración de salida (FOAM): Proporciona una asignación de la frecuencia de vibración a la aceleración de salida máxima alcanzable para el dispositivo.
• Compose PWLE: Reproduce una vibración definida por un PWLE de la forma de onda de vibración.

API básica de PWLE

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

• El valor de Intensity 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 Sharpness 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.
• Duración es el tiempo que se tarda en realizar la transición del último punto de PWLE (es decir, el par de intensidad y nitidez) al nuevo, en milisegundos.

Este es un ejemplo de forma de onda que aumenta la intensidad de un tono bajo a un tono alto de vibración de máxima intensidad en 500 ms y, luego, disminuye a 0 (desactivada) en 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 inconvenientes, los efectos de PWLE deben comenzar y terminar con una intensidad de 0.0. La API aplica esto corrigiendo la intensidad de inicio en 0 y arroja 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 una renderización de efectos de PWLE coherente en todo el ecosistema de Android, el framework requiere que los dispositivos compatibles con 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. Estos requisitos se aplican mediante pruebas de VTS, lo que ayuda a garantizar efectos de PWLE confiables en todos los dispositivos Android.

API avanzada de PWLE

Los desarrolladores con conocimientos avanzados en tecnología táctil pueden definir los 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 determine la FOAM del dispositivo. Por ejemplo, un valor de 0.5 genera la mitad de la aceleración máxima de salida que se puede lograr a la frecuencia determinada.
• La frecuencia se especifica directamente en hercios.
• Duración (Duration) es el tiempo que se tarda en realizar la transición del último punto de PWLE al nuevo, en milisegundos.

A continuación, se muestra una forma de onda de ejemplo que aumenta la amplitud de un vibrador de apagado a completa a 120 Hz en 100 ms, mantiene ese estado durante 200 ms y, luego, vuelve a disminuir en 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 de 0 para garantizar una transición fluida.

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

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

La representación precisa de la frecuencia de un dispositivo para generar capacidades de aceleración es fundamental 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 compatibles con los efectos de PWLE deben proporcionar una frecuencia para generar un mapa de aceleración de salida (FOAM). El FOAM es una estructura de datos que genera el HAL que asigna la frecuencia de vibración (en hercios) a la aceleración de salida máxima alcanzable 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 básica de PWLE.

En la siguiente gráfica, se muestra un ejemplo de un FOAM para un actuador resonante típico, con un 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 tiene tres propósitos clave:

• Definir el rango de frecuencia completo: El FOAM define el rango de frecuencia completo del dispositivo especificando las frecuencias de vibración mínimas y máximas compatibles.
• Definición de los valores de intensidad y nitidez: La API básica de PWLE 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. Esta asignación ayuda a garantizar que los efectos táctiles 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 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 logre el nivel de intensidad seleccionado sin salirse de las capacidades del dispositivo.
• Exposición de las capacidades de hardware: El FOAM se expone a los desarrolladores en VibratorFrequencyProfile, lo que proporciona la frecuencia completa para generar un conjunto de datos de aceleración que detalla algunas de las capacidades táctiles 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.

FOAM y la API básica de PWLE

La espuma juega un papel vital en la forma 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 el usuario pueda percibir las vibraciones. Este rango corresponde a frecuencias en las que la aceleración de salida es de al menos 10 dB por encima del umbral de detección de 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 básica de PWLE a sus valores de amplitud y frecuencia correspondientes. Esta asignación ayuda a producir una respuesta táctil perceptible en diferentes dispositivos.

Las pruebas de VTS se implementan para garantizar 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ínimas y máximas compatibles del dispositivo, en hercios, con getMinFrequencyHz y getMaxFrequencyHz, respectivamente.
• Aceleración máxima de salida: La aceleración máxima de salida que puede lograr el 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 como se implementa en el sistema HAL.

Los desarrolladores pueden usar esta información cuando crean efectos de envolvente con la API de PWLE avanzada. 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 avanzada de PWLE, 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 superen sus capacidades.

Umbral de detección de percepción humana

El umbral de detección de percepción humana se refiere 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.

En el siguiente gráfico, se muestra el umbral de detección de 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 forma 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 percepción humana en 10 dB.

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

La percepción humana de la intensidad de la vibración (una medida de percepción) no crece de manera 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 un 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 vibración (en G máximo) se puede calcular de la siguiente manera:

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

Donde la amplitud en dB es la suma de la SL 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 paires sucesivos de puntos de control.

En el siguiente gráfico, se muestran 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 percepción táctil humana (0 dB SL), como una función de la frecuencia temporal.

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

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

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

Obtén la curva de voltaje máxima (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 a través de varias metodologías. En esta sección, se muestra un método para dispositivos que usan actuadores resonantes lineales (LRAs).

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: Es el nivel de voltaje real aplicado al actuador táctil.

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

Loc_coeff: Es el 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: Es la masa del dispositivo (por ejemplo, un teléfono).

w: Es la frecuencia angular (radianes por segundo) de la señal de conducción, que se calcula de la siguiente manera:

\(w = 2 \pi f\)

Psys_abs: Es la respuesta de amplitud de un sistema de masa, amortiguador y resorte de segundo orden, que se calcula 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 relació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 representa 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 hercios, por lo que el HAL debe convertir la unidad de frecuencia de radianes por segundo a hercios cuando genera los datos de FOAM.

Genera la curva 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 a esa frecuencia con la ecuación anterior y sustituye 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).

Cómo exponer los datos de FOAM

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

Si bien no hay requisitos estrictos para la resolución de la FOAM, te recomendamos que definas 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 valores de aceleración intermedios, te recomendamos definir una resolución de alta frecuencia 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 el caso de Android 16 y versiones posteriores, para ayudar a los desarrolladores a optimizar sus efectos de PWLE y garantizar la compatibilidad entre 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 lo muestra cuando el dispositivo admite esta función.
• getFrequencyToOutputAccelerationMap: Recupera los datos de FOAM.
• getPwleV2PrimitiveDurationMinMillis: Recupera la duración mínima permitida para cualquier PWLE primitivo en milisegundos.
• getPwleV2PrimitiveDurationMaxMillis: Recupera la duración máxima permitida para cualquier PWLE primitivo en milisegundos.
• getPwleV2CompositionSizeMax: Recupera la cantidad máxima de primitivas de PWLE que admite IVibrator.composePwleV2.

Esta información se expone a los desarrolladores para permitirles adaptar sus efectos a las capacidades específicas del dispositivo de destino, especialmente 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 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 el propósito y el estilo originales del diseño tanto como sea posible.