Implementar efeitos de envelope linear em trechos

Os efeitos de envelope linear por partes (PWLE, na sigla em inglês) são sequências de pontos que definem a frequência e a aceleração da vibração ao longo do tempo. Os PWLEs oferecem retorno tátil mais rico e dinâmico.

O Android 16 e versões mais recentes oferecem duas APIs de desenvolvedor de apps para ajudar a criar efeitos PWLE:

• API PWLE básica:simples, mas com limitações. Boa para começar rapidamente. Disponível em BasicEnvelopeBuilder.
• API PWLE avançada:mais controle e flexibilidade, exige conhecimento de háptica e alguma familiaridade com hardware. Disponível em WaveformEnvelopeBuilder.

Para oferecer suporte a essas APIs, os dispositivos precisam implementar as seguintes APIs HAL:

• Frequência de ressonância:fornece a frequência de ressonância do atuador.
• Mapeamento de frequência para aceleração de saída (FOAM, na sigla em inglês) : fornece um mapeamento da frequência de vibração para a aceleração de saída máxima alcançável para o dispositivo.
• Compor PWLE:reproduz uma vibração definida por um PWLE da forma de onda de vibração.

Observação: esclarecimento da terminologia: esta página usa amplitude e frequência para medições físicas e intensidade e nitidez para parâmetros perceptivos.

API PWLE básica

Para uma maneira rápida de criar efeitos PWLE sem se aprofundar no hardware ou nas nuances da percepção humana, os desenvolvedores podem usar a API PWLE básica, definida usando estes parâmetros:

• O valor de intensidade no intervalo de [0, 1] representa a força percebida da vibração. Por exemplo, um valor de 0,5 é percebido como metade da intensidade máxima global que pode ser alcançada pelo dispositivo.
• O valor de nitidez no intervalo de [0, 1] representa a nitidez da vibração. Valores mais baixos se traduzem em vibrações mais suaves, enquanto valores mais altos criam uma sensação mais nítida.
• Duração é o tempo necessário para fazer a transição do último ponto PWLE (ou seja, o par de intensidade e nitidez) para o novo, em milissegundos.

Observação: a intensidade percebida da vibração não é mapeada linearmente para a aceleração de saída da vibração. O framework do Android traduz o parâmetro de envelope de intensidade para a amplitude de vibração, levando em consideração a lei de potência que rege a relação entre a intensidade de vibração percebida e a amplitude de aceleração da vibração. Essa amplitude traduzida é enviada para a implementação de hardware.

Confira um exemplo de forma de onda que aumenta a intensidade de um tom baixo para uma vibração de força máxima de tom alto em 500 ms e, em seguida, diminui para 0 (desligado) em 100 ms:

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

Restrições

Para criar uma experiência tátil suave e integrada, os efeitos PWLE precisam começar e terminar com uma intensidade de 0,0. A API aplica isso fixando a intensidade inicial em 0 e gera uma exceção se a intensidade final não for 0. Essa restrição impede efeitos dinâmicos indesejáveis nas vibrações devido a descontinuidades na amplitude que podem afetar negativamente a percepção tátil do usuário.

Para garantir a renderização consistente do efeito PWLE em todo o ecossistema Android, o framework exige que os dispositivos que oferecem suporte a esse recurso possam processar uma duração mínima de 20 ms entre os pontos PWLE e pelo menos 16 pontos para efeitos PWLE. Esses requisitos são aplicados por testes VTS, ajudando a garantir efeitos PWLE confiáveis em dispositivos Android.

API PWLE avançada

Os desenvolvedores com conhecimento avançado em háptica podem definir efeitos PWLE usando estes critérios:

• O valor de amplitude no intervalo de [0, 1] representa a força alcançável em uma determinada frequência, conforme determinado pelo FOAM do dispositivo. Por exemplo, um valor de 0,5 gera metade da aceleração de saída máxima que pode ser alcançada na frequência especificada.
• A frequência é especificada diretamente em Hertz.
• Duração é o tempo necessário para fazer a transição do último ponto PWLE para o novo, em milissegundos.

Confira um exemplo de forma de onda que aumenta um vibrador de desligado para amplitude total a 120 Hz em 100 ms, mantém esse estado por 200 ms e, em seguida, diminui novamente em 100 ms:

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

Restrições

O framework não modifica os valores de frequência e amplitude solicitados fornecidos pelo desenvolvedor, mas adiciona um ponto de partida de amplitude 0 para garantir uma transição suave.

Os desenvolvedores são responsáveis por garantir que a frequência especificada nos efeitos PWLE esteja dentro do intervalo compatível do dispositivo, conforme definido pelo FOAM do dispositivo. Se os valores excederem esses limites, o dispositivo não vai reproduzir nenhuma vibração.

Mapeamento de frequência para aceleração de saída (FOAM)

A representação precisa da frequência de um dispositivo para recursos de aceleração de saída é essencial para oferecer suporte às APIs PWLE. Esta seção detalha a importância desses dados, como eles são usados pelas APIs PWLE e o processo de geração deles.

Entender o mapeamento

Os dispositivos que oferecem suporte a efeitos PWLE precisam fornecer um mapa de frequência para aceleração de saída (FOAM). O FOAM é uma estrutura de dados gerada pelo HAL que mapeia a frequência de vibração (em Hertz) para a aceleração de saída máxima alcançável do atuador (em G de pico) nessa frequência. Esse mapa é fundamental para entender como a saída de vibração varia para o intervalo de frequência compatível e para definir a API PWLE básica.

O gráfico a seguir mostra um exemplo de FOAM para um atuador ressonante típico, com tensão de entrada limitada em torno da frequência de ressonância para proteger o motor:

Figura 1. Exemplo de FOAM para um atuador ressonante típico.

O FOAM tem três finalidades principais:

• Definir o intervalo de frequência completo:o FOAM define o intervalo de frequência completo do dispositivo especificando as frequências de vibração mínima e máxima compatíveis.
• Definir os valores de intensidade e nitidez:a API PWLE básica opera em uma escala de percepção humana para intensidade e nitidez, que são mapeadas para parâmetros de frequência e amplitude de hardware usando os valores de aceleração de saída no FOAM. Esse mapeamento ajuda a garantir que os efeitos táteis sejam renderizados de acordo com os recursos de hardware. O intervalo de nitidez é definido pelo limite mínimo perceptível e corresponde às frequências em que o dispositivo pode produzir efeitos táteis que os usuários podem sentir. O framework mapeia os valores de intensidade para a amplitude com base na aceleração de saída de destino na frequência selecionada. Isso ajuda a garantir que o nível de intensidade selecionado seja alcançado, mantendo-se dentro dos recursos do dispositivo.
• Expor recursos de hardware: o FOAM é exposto aos desenvolvedores em VibratorFrequencyProfile, fornecendo o conjunto de dados completo de frequência para aceleração de saída detalhando alguns dos recursos táteis do dispositivo. Esses dados permitem que os desenvolvedores que usam a API PWLE avançada criem efeitos de vibração personalizados que vão além dos intervalos básicos de intensidade e nitidez definidos pelo framework.

FOAM e API PWLE básica

O FOAM desempenha um papel fundamental na formação de efeitos de vibração. Ele é usado para calcular o intervalo de nitidez da API de envelope básica, garantindo que as vibrações sejam perceptíveis ao usuário. Esse intervalo corresponde às frequências em que a aceleração de saída atinge 10 dB acima do limite de detecção de percepção humana (ou seja, o nível mínimo perceptível) até o ponto em que a aceleração de saída está acima desse limite. Esse intervalo precisa incluir a frequência de ressonância do atuador.

Além disso, o framework usa os dados do FOAM para mapear os valores de intensidade e nitidez usados na API PWLE básica para os valores de amplitude e frequência correspondentes. Esse mapeamento ajuda a produzir retorno tátil perceptível em diferentes dispositivos.

Os testes VTS são realizados para garantir que os dispositivos que oferecem suporte a efeitos de envelope tenham um intervalo de frequência não vazio que produza vibrações perceptíveis e que o intervalo contenha a frequência de ressonância do atuador. Isso ajuda a garantir que o dispositivo possa produzir vibrações com intensidade suficiente para serem claramente sentidas pelos usuários.

FOAM e API PWLE avançada

O FOAM é exposto aos desenvolvedores por VibratorFrequencyProfile com as seguintes informações:

• Intervalo de frequência: os desenvolvedores podem recuperar as frequências mínima e máxima compatíveis do dispositivo, em Hertz, usando getMinFrequencyHz e getMaxFrequencyHz, respectivamente.
• Aceleração de saída máxima: a aceleração de saída máxima alcançável do dispositivo (em G) está disponível em getMaxOutputAccelerationGs.
• Mapeamento de frequência para aceleração de saída: getFrequenciesOutputAcceleration fornece o mapeamento de frequência para aceleração de saída conforme implementado no HAL.

Os desenvolvedores podem usar essas informações ao criar efeitos de envelope com a API PWLE avançada. Por exemplo, ao especificar uma aceleração de saída (em G), eles precisam normalizá-la para um valor dentro do intervalo [0,0, 1,0], em relação à aceleração de saída máxima do dispositivo.

Com a API PWLE avançada, os desenvolvedores podem usar todo o intervalo de frequência. Portanto, é fundamental que os dados do FOAM fornecidos sejam seguros para o vibrador e não excedam os recursos dele.

Limite de detecção de percepção humana

O limite de detecção de percepção humana se refere à aceleração mínima de uma vibração que uma pessoa pode detectar de forma confiável. Esse nível varia com base na frequência de vibração.

O gráfico a seguir mostra o limite de detecção de percepção tátil humana¹, em aceleração, como uma função da frequência temporal:

Figura 2. Limite de detecção de percepção tátil humana.

Para que os usuários possam sentir os efeitos táteis de forma consistente, os testes VTS validam se os dispositivos com recursos de envelope têm um intervalo de frequência que pode produzir amplitudes de vibração que excedam o limite de detecção de percepção humana em 10 dB.

Intensidade de vibração percebida versus amplitude de aceleração de vibração

A percepção humana da intensidade de vibração (uma medida de percepção) não cresce linearmente com a amplitude de vibração (um parâmetro físico). A API PWLE pressupõe que, quando um designer ou desenvolvedor pensa em mudanças na força de vibração, ele espera que a intensidade percebida siga um PWLE. A intensidade percebida é caracterizada pelo nível de sensação (SL, na sigla em inglês), que é definido como dB acima do limite de detecção na mesma frequência. Assim, a amplitude de aceleração de vibração (em G de pico) pode ser calculada da seguinte maneira:

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

Em que a amplitude dB é a soma do SL e do limite de detecção (o valor ao longo da ordenada no gráfico a seguir) em uma frequência específica.

Dessa forma, a API PWLE garante que a intensidade percebida mude linearmente entre pares sucessivos de pontos de controle.

O gráfico a seguir mostra os níveis de aceleração de vibração² em 10, 20, 30, 40 e 50 dB SL, juntamente com o limite de detecção de percepção tátil humana (0 dB SL), como uma função da frequência temporal.

Figura 3. Níveis de aceleração de vibração.

Determinar a frequência para a curva de aceleração de saída máxima

Esta seção fornece uma diretriz geral sobre como obter a frequência para a curva de aceleração de saída máxima do dispositivo, que você usa para gerar os dados do FOAM.

Obter a curva de tensão máxima (V)

V é a tensão máxima que pode ser aplicada com segurança ao vibrador no intervalo de frequência operacional. Isso garante que o vibrador opere dentro de limites seguros, evitando danos e maximizando a saída de vibração.

Cuidado:há diferentes métodos para determinar essa curva, mas é fundamental garantir que as tensões medidas estejam dentro do intervalo operacional seguro do hardware para evitar danos.

Se o hardware incluir um recurso de limitação de tensão, use-o para medir diretamente a tensão máxima alcançável em todo o intervalo de frequência compatível.

Calcular a aceleração máxima (M)

M é a aceleração máxima, que pode ser calculada usando várias metodologias. Esta seção mostra um método para dispositivos que usam atuadores ressonantes lineares (LRAs, na sigla em inglês).

Esse método converte a tensão máxima aplicada em uma determinada frequência em um valor de aceleração máxima correspondente, expresso em G de pico.

A equação principal usada para essa conversão é:

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

Em que:

Vsys: nível de tensão real aplicado ao atuador tátil

BLsys: produto da intensidade do campo magnético (B) e do comprimento do condutor (L) de o motor de vibração

Loc_coeff: coeficiente de localização para converter a aceleração no nível do módulo em aceleração no nível do smartphone

Rsys: resistência elétrica da bobina do motor de vibração

MPhone: massa do dispositivo (por exemplo, smartphone)

w: frequência angular (radianos por segundo) do sinal de acionamento, calculada como:

\(w = 2 \pi f\)

Psys_abs: resposta de amplitude de um sistema de massa, amortecedor e mola de segunda ordem, calculada como:

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

Wnsys: frequência natural do sistema vibratório

Qsys: fator de qualidade do sistema vibratório

Loc_coeff é a proporção da aceleração medida no nível do smartphone para a aceleração medida no nível do módulo. Essa proporção é usada para converter leituras de aceleração no nível do módulo em leituras de aceleração equivalentes no nível do smartphone. No nível do smartphone, devido à aceleração angular do movimento do módulo, a aceleração é amplificada, e esse coeficiente considera esse tipo de efeito. Ele é calculado como:

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

Por exemplo, se a aceleração do módulo for 1 g e a aceleração do smartphone for 2,5 g, então Loc_coeff = 2,5. Isso indica uma amplificação de 2,5 vezes.

O framework do Android usa a frequência na unidade de Hertz. Portanto, o HAL precisa converter a unidade de frequência de radianos por segundo para Hertz ao gerar os dados do FOAM.

Gerar a curva do FOAM

Combine a curva de tensão máxima (V) e o cálculo de aceleração (M) para determinar a curva do FOAM:

• Para cada frequência (f) no intervalo desejado, encontre a tensão máxima correspondente V(f) na curva de tensão máxima.
• Calcule a aceleração máxima nessa frequência usando a equação acima, substituindo V(f) por Vsys e o f correspondente por w. Isso fornece M(V(f), f).
• Essa aceleração calculada é o valor FOAM(f).

Expor os dados do FOAM

Depois que a curva do FOAM é gerada, o HAL a representa como uma lista de objetos FrequencyAccelerationMapEntry. Cada entrada define um ponto no mapeamento, especificando uma frequência (em Hertz) e a aceleração de saída máxima correspondente (em G de pico).

Para otimizar a acurácia da interpolação linear ao determinar valores de aceleração intermediários, recomendamos definir uma resolução de alta frequência em torno da frequência com aceleração de saída máxima. Por exemplo, use etapas de 1 Hz no intervalo de +/- 10 Hz dessa frequência.

Recursos e limitações do dispositivo

No Android 16 e versões mais recentes, para ajudar os desenvolvedores a otimizar os efeitos PWLE e garantir a compatibilidade entre dispositivos, o Android inclui APIs HAL para consultar os recursos PWLE do dispositivo. Esses métodos fornecem informações sobre as limitações do dispositivo, como a duração mínima ou máxima do primitivo PWLE e o número de primitivos permitidos em uma composição PWLE.

As APIs HAL incluem:

• CAP_COMPOSE_PWLE_EFFECTS_V2: é retornado por IVibrator.getCapabilities quando o dispositivo oferece suporte a esse recurso.
• getFrequencyToOutputAccelerationMap: recupera os dados do FOAM.
• getPwleV2PrimitiveDurationMinMillis: recupera a duração mínima permitida para qualquer PWLE primitivo em milissegundos.
• getPwleV2PrimitiveDurationMaxMillis: recupera a duração máxima permitida para qualquer PWLE primitivo em milissegundos.
• getPwleV2CompositionSizeMax: recupera o número máximo de primitivos PWLE com suporte de IVibrator.composePwleV2.

Essas informações são expostas aos desenvolvedores para permitir que eles personalizem os efeitos de acordo com os recursos específicos do dispositivo de destino, especialmente ao usar a API PWLE avançada.

O framework também usa essas APIs ao processar efeitos criados com a API básica. Se um efeito exceder as limitações do dispositivo (por exemplo, muitos pontos PWLE ou uma duração que exceda o máximo), o framework ajustará automaticamente o efeito para se ajustar aos limites permitidos. Esse processo de ajuste tenta preservar a intenção e a sensação originais do design o máximo possível.

---

1. Os dados de limite são convertidos do limite de deslocamento na 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). Este tutorial on-line explica a conversão entre a amplitude de aceleração e a amplitude de deslocamento. ↩

2. Os dados são estimados na Figura 8 em Verrillo, R. T., et al. "Sensation magnitude of vibrotactile stimuli." Perception &Psychophysics 6: 366-372 (1969). ↩