Implementar efeitos de envelope linear em trechos

Os efeitos de envelope linear em 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 um feedback tátil mais rico e dinâmico.

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

• API PWLE básica:simples, mas com limitações. É bom para começar rapidamente. Disponível em BasicEnvelopeBuilder.
• API PWLE avançada:mais controle e flexibilidade, requer 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:

• 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 do dispositivo.
• Criar PWLE:toca uma vibração definida por uma PWLE da forma de onda da vibração.

API PWLE básica

Para criar efeitos de PWLE sem precisar 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 intensidade 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 resultam em vibrações mais suaves, enquanto valores mais altos criam uma sensação mais nítida.
• Duração é o tempo que leva para fazer a transição do último ponto de PWLE (ou seja, o par de intensidade e nitidez) para o novo, em milissegundos.

Confira um exemplo de forma de onda que aumenta a intensidade de um tom baixo para um tom alto de vibração de força máxima em 500 ms e depois diminui para 0 (desativado) 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 contínua, os efeitos de 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 evita efeitos dinâmicos indesejáveis nas vibrações devido a discontinuidades na amplitude que podem afetar negativamente a percepção táctil do usuário.

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

API PWLE avançada

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

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

Confira um exemplo de forma de onda que aumenta a amplitude de um vibrador de desligado para 120 Hz em 100 ms, mantém esse estado por 200 ms e depois diminui por mais 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 de PWLE esteja dentro do intervalo de suporte do dispositivo, conforme definido pelo FOAM do dispositivo. Se os valores excederem esses limites, o dispositivo não vai emitir vibrações.

Mapeamento de frequência para aceleração de saída (FOAM, na sigla em inglês)

A representação precisa da frequência de um dispositivo para os 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.

Entender o mapeamento

Os dispositivos que oferecem suporte a efeitos PWLE precisam fornecer um mapa de aceleração de frequência para saída (FOAM, na sigla em inglês). 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 atingível do atuador (em G de pico) nessa frequência. Esse mapa é crucial para entender como a saída de vibração varia para o intervalo de frequências aceito e para definir a API PWLE básica.

O gráfico a seguir mostra um exemplo de um FOAM para um atuador de ressonância típico, com a 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 de ressonância típico.

O FOAM tem três finalidades principais:

• Definição do intervalo de frequência total:o FOAM define o intervalo de frequência total do dispositivo especificando as frequências de vibração mínima e máxima compatíveis.
• Como definir os valores de intensidade e nitidez:a API PWLE básica opera em uma escala de percepção humana de 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 hápticos que os usuários podem sentir. O framework mapeia os valores de intensidade para a amplitude com base na aceleração de saída alvo 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.
• Exposição de recursos de hardware:o FOAM é exposto aos desenvolvedores em VibratorFrequencyProfile, fornecendo o conjunto de dados de aceleração de saída completo, detalhando alguns dos recursos hápticos do dispositivo. Esses dados permitem que os desenvolvedores usem a API PWLE avançada para criar 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

A FOAM desempenha um papel vital na formação dos 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 para o usuário. Esse intervalo corresponde a frequências em que a aceleração de saída é de pelo menos 10 dB acima do limiar de detecção de percepção humana (ou seja, o nível mínimo perceptível) para cada frequência. Isso garante que as vibrações sejam fortes o suficiente para serem sentidas.

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 um feedback tátil perceptível em diferentes dispositivos.

Os testes do VTS estão em vigor para garantir que os dispositivos que oferecem suporte a efeitos de envelope tenham um intervalo de frequência não vazio que produz vibrações perceptíveis. 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:

• Faixa de frequência:os desenvolvedores podem extrair as frequências mínima e máxima suportadas pelo dispositivo, em Hertz, usando getMinFrequencyHz e getMaxFrequencyHz, respectivamente.
• Aceleração máxima de saída:a aceleração máxima de saída 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 a 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), é necessário normalizar o 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 da percepção humana se refere à aceleração mínima de uma vibração que uma pessoa pode detectar com confiabilidade. Esse nível varia de acordo com a frequência da vibração.

O gráfico a seguir mostra o limiar 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 hápticos de forma consistente, os testes VTS validam que dispositivos com recursos de envelope têm um intervalo de frequência que pode produzir amplitudes de vibração que excedem o limite de detecção de percepção humana em 10 dB.

Intensidade da vibração percebida em relação à amplitude da aceleração da vibração

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

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

Em que o dB de amplitude é 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 da vibração² em 10, 20, 30, 40 e 50 dB SL, além do limiar 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 da vibração.

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

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

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

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

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 toda a faixa de frequência suportada.

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

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

Esse método converte a tensão máxima aplicada em uma determinada frequência em um valor máximo de aceleração 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 háptico

BLsys: produto da intensidade do campo magnético (B) e do comprimento do condutor (L) do 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 de vibração

Loc_coeff é a proporção da aceleração medida no nível do smartphone em relação à 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 é responsável por esse tipo de efeito. O cálculo é feito da seguinte forma:

\(\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, 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 FOAM

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

• Para cada frequência (f) no intervalo desejado, encontre a tensão máxima V(f) correspondente da 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 gera M(V(f), f).
• Essa aceleração calculada é o valor de FOAM(f).

Expor os dados do FOAM

Depois que a curva FOAM é gerada, o HAL representa a curva 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 pico).

Embora não haja requisitos rígidos para a resolução da FOAM, recomendamos definir curvas com um pico máximo. Somente o primeiro pico é usado na API de envelope básico para mapear os efeitos de vibração. Para otimizar a precisão da interpolação linear ao determinar valores de aceleração intermediários, recomendamos definir uma resolução de alta frequência ao redor do pico. Por exemplo, use incrementos de 1 Hz dentro do intervalo de +/- 10 Hz da frequência de pico.

Recursos e limitações do dispositivo

No Android 16 e versões mais recentes, para ajudar os desenvolvedores a otimizar os efeitos de PWLE e garantir a compatibilidade entre dispositivos, o Android inclui APIs HAL para consultar os recursos de PWLE do dispositivo. Esses métodos fornecem informações sobre as limitações do dispositivo, como a duração mínima ou máxima da PWLE e o número de primitivas permitidos em uma composição de 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 primitivas PWLE com suporte a IVibrator.composePwleV2.

Essas informações são expostas aos desenvolvedores para que eles possam adaptar os efeitos aos 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 vai 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.