Implementar efeitos de envelope linear em trechos

Os efeitos de envelope linear segmentado (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. As 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 que ajudam a criar efeitos PWLE:

• API PWLE básica:simples, mas com limitações. Ideal 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:

• Mapeamento da frequência para aceleração de saída (FOAM): fornece um mapeamento da frequência de vibração para a aceleração de saída máxima possível para o dispositivo.
• Compor PWLE:reproduz uma vibração definida por uma PWLE da forma de onda de vibração.

API PWLE básica

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

• O valor Intensity no intervalo [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 [0, 1] representa a nitidez da vibração. Valores mais baixos significam 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.

Confira um exemplo de forma de onda que aumenta a intensidade de um tom baixo para uma vibração de tom alto e intensidade máxima em 500 ms e depois 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 de PWLE precisam começar e terminar com uma intensidade de 0,0. A API faz isso corrigindo a intensidade inicial em 0 e gerando 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 descontinuidades na amplitude que podem afetar negativamente a percepção háptica do usuário.

Para garantir uma renderização consistente do efeito PWLE em todo o ecossistema Android, o framework exige que os dispositivos compatíveis com esse recurso possam processar uma duração mínima de 10 ms entre pontos PWLE e pelo menos 16 pontos para efeitos PWLE. Esses requisitos são aplicados por testes do VTS, ajudando a garantir efeitos de 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 da amplitude no intervalo [0, 1] representa a intensidade 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 máxima de saída que pode ser alcançada na determinada frequência.
• A frequência é especificada diretamente em Hertz.
• Duração é o tempo gasto 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 depois diminui 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 de PWLE esteja dentro do intervalo compatível do dispositivo, conforme definido pela FOAM do dispositivo. Se os valores excederem esses limites, o dispositivo não vai emitir nenhuma vibração.

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 gerar recursos de aceleração é 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.

Entenda o mapeamento

Os dispositivos que oferecem suporte a efeitos PWLE precisam fornecer uma frequência para gerar um mapa de aceleração de saída (FOAM, na sigla em inglês). O FOAM é uma estrutura de dados gerada pela HAL que mapeia a frequência de vibração (em Hertz) para a aceleração máxima de saída (em G de pico) que o atuador pode alcançar nessa frequência. Esse mapa é crucial 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 um FOAM para um atuador ressonante típico.

O FOAM tem três propósitos 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.
• 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 hápticos sejam renderizados de acordo com os recursos de hardware. O intervalo de nitidez é definido pelo limiar mínimo perceptível e corresponde às frequências em que o dispositivo pode produzir efeitos hápticos que os usuários podem sentir. A estrutura mapeia os valores de intensidade para amplitude com base na aceleração de saída desejada na frequência selecionada. Isso ajuda a garantir que o nível de intensidade selecionado seja alcançado sem exceder as capacidades do dispositivo.
• Exposição de recursos de hardware:o FOAM é exposto aos desenvolvedores em VibratorFrequencyProfile, fornecendo a frequência completa para gerar um conjunto de dados de aceleração detalhando alguns dos recursos hápticos 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

A espuma tem um papel fundamental na criação de efeitos de vibração. Usado para calcular o intervalo de nitidez da API Envelope básico, 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 não é inferior a 10 dB acima do limite de detecção da 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 correspondentes de amplitude e frequência. Esse mapeamento ajuda a produzir feedback háptico perceptível em diferentes dispositivos.

Os testes do VTS garantem que os dispositivos compatíveis com efeitos de envelope tenham um intervalo de frequência não vazio que produza 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 pelo 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 máxima de saída:a aceleração máxima de saída (em G) que o dispositivo pode alcançar 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 implementado na 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 para um valor no intervalo [0,0, 1,0], em relação à aceleração máxima de saída do dispositivo.

Com a API PWLE avançada, os desenvolvedores podem usar toda a faixa de frequência. Por isso, é fundamental que os dados de 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 de acordo com a frequência da vibração.

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

Figura 2. Limite de detecção da percepção háptica humana.

Para que os usuários sintam os efeitos hápticos de forma consistente, os testes do 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 da percepção humana em 10 dB.

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

A percepção humana da intensidade da vibração (uma medida de percepção) não cresce linearmente com a amplitude da vibração (um parâmetro físico). A API PWLE pressupõe 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 de G) pode ser calculada da seguinte forma:

\(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 determinada frequência.

Assim, 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, além do limite de detecção da percepção háptica humana (0 dB SL), como uma função da frequência temporal.

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

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

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

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

V é a tensão máxima que pode ser aplicada com segurança ao vibrador na faixa de frequência operacional. Isso garante que o vibrador funcione 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 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 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 modo vibratório.

MPhone: massa do dispositivo (por exemplo, smartphone)

w: frequência angular (radianos por segundo) do sinal de direção, calculada como:

\(w = 2 \pi f\)

Psys_abs: resposta de amplitude de um sistema de massa, amortecedor e mola de segunda ordem, calculado 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 e do módulo. Essa proporção é usada para converter leituras de aceleração no nível do módulo em leituras 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 explica esse tipo de efeito. Ele é calculado assim:

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

Por exemplo, se a aceleração do módulo for 1 g e a 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 frequência na unidade de Hertz. Portanto, a HAL precisa converter a unidade de frequência de radianos por segundo para Hertz ao gerar os dados de 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 de 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 dá a você M(V(f), f).
• Essa aceleração calculada é o valor de FOAM(f).

Expor os dados do FOAM

Depois que a curva FOAM é gerada, a 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 máxima de saída correspondente (em G de pico).

Embora não haja requisitos rigorosos para a resolução do 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 em torno do pico. Por exemplo, use etapas de 1 Hz no 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 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 da primitiva PWLE e o número de primitivas permitidas em uma composição PWLE.

As APIs HAL incluem:

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

Essas informações são expostas aos desenvolvedores para que eles possam adaptar os efeitos às capacidades específicas 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 excede o máximo), o framework vai ajustar automaticamente o efeito para se adequar aos limites permitidos. Esse processo de ajuste tenta preservar a intenção e a sensação originais do design o máximo possível.