区分的線形エンベロープ エフェクトを実装する

区分線形エンベロープ（PWLE）効果は、時間経過に伴う振動周波数と加速度を定義する一連の点です。PWLE は、より豊かでダイナミックな触覚フィードバックを提供します。

Android 16 以降では、PWLE 効果の作成に役立つ 2 つのアプリ デベロッパー API が提供されています。

  • 基本 PWLE API: シンプルですが、制限があります。すぐに使い始めるのに適しています。BasicEnvelopeBuilder で使用できます。
  • 高度な PWLE API: 制御と柔軟性が向上しています。ハプティクスの知識とハードウェアに関するある程度の知識が必要です。 WaveformEnvelopeBuilder で使用できます。

これらの API をサポートするには、デバイスで次の HAL API を実装する必要があります。

  • 共振周波数: アクチュエータの共振周波数を指定します。
  • 周波数から出力加速度へのマッピング（FOAM）: デバイスの振動周波数から達成可能な最大出力加速度へのマッピングを指定します。
  • PWLE の構成: 振動波形の PWLE で定義されたバイブレーションを再生します。

基本 PWLE API

ハードウェアや人間の知覚のニュアンスに踏み込むことなく PWLE 効果をすばやく作成するには、デベロッパーは次のパラメータを使用して定義された基本 PWLE API を使用できます。

  • [強度] の値は [0, 1] の範囲で、振動の知覚される強さを表します。たとえば、値が 0.5 の場合、デバイスで達成可能なグローバル最大強度の半分として認識されます。
  • [鮮明度] の値は [0, 1] の範囲で、振動の鮮明度を表します。値が小さいほど振動がスムーズになり、値が大きいほど鮮明な感覚が得られます。
  • [長さ] は、最後の PWLE ポイント（強度とシャープネスのペア）から新しいポイントに移行するまでの時間（ミリ秒単位）です。

次の波形は、500 ミリ秒かけて低音から高音の最大強度のバイブレーションまで強度を上げ、100 ミリ秒かけて 0（オフ）まで下げる例です。

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

制約

スムーズでシームレスな触覚体験を実現するには、PWLE 効果を 0.0 の強度で開始し、終了する必要があります 。API は、開始強度を 0 に固定することでこれを強制し、終了強度が 0 でない場合は例外をスローします。この制約により、振幅の不連続性による振動の望ましくない動的効果を防ぎ、ユーザーの触覚認識に悪影響を与えないようにします。

Android エコシステム全体で PWLE 効果のレンダリングの一貫性を確保するため、フレームワークでは、この機能をサポートするデバイスが PWLE ポイント間で最小 20 ミリ秒の期間を処理でき、PWLE 効果に少なくとも 16 ポイントを使用できることが求められます。これらの要件は VTS テストによって強制され、 Android デバイス全体で信頼性の高い PWLE 効果を確保するのに役立ちます。

高度な PWLE API

ハプティクスに関する高度な知識を持つデベロッパーは、次の条件を使用して PWLE 効果を定義できます。

  • [振幅] の値は [0, 1] の範囲で、デバイスの FOAM によって決定される、特定の周波数で達成可能な強さを表します。たとえば、値が 0.5 の場合、特定の周波数で達成可能な最大出力加速度の半分が生成されます。
  • [周波数] はヘルツで直接指定します。
  • [長さ] は、最後の PWLE ポイントから新しいポイントに移行するまでの時間（ミリ秒単位）です。

次の波形は、100 ミリ秒かけてバイブレータをオフから 120 Hz の最大振幅まで上げ、その状態を 200 ミリ秒間保持し、100 ミリ秒かけて下げる例です。

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

制約

フレームワークは、デベロッパーが指定したリクエストされた周波数と振幅の値を変更しませんが、スムーズな移行を確保するために 0 振幅の開始点を追加します。

デベロッパーは、デバイスの FOAM で定義されているように、PWLE 効果で指定された周波数がデバイスのサポート範囲内にあることを確認する必要があります。値がこれらの上限を超えると、デバイスはバイブレーションを再生しません。

周波数から出力加速度へのマッピング（FOAM）

PWLE API をサポートするには、デバイスの周波数から出力加速度への機能を正確に表現することが不可欠です。このセクションでは、このデータの重要性、PWLE API での使用方法、生成プロセスについて詳しく説明します。

マッピングについて

PWLE 効果をサポートするデバイスは、周波数から出力加速度へのマッピング（FOAM）を提供する必要があります。FOAM は、HAL によって生成されるデータ構造であり、振動周波数（ヘルツ単位）を、その周波数でのアクチュエータの達成可能な最大出力加速度（G ピーク）にマッピングします。このマップは、サポートされている周波数範囲でバイブレーション出力がどのように変化するかを理解し、基本 PWLE API を定義するうえで重要です。

次のプロットは、一般的な共振アクチュエータの FOAM の例を示しています。モーターを保護するため、共振周波数付近で入力電圧が制限されています。

FOAM の例

図 1.一般的な共振アクチュエータの FOAM の例。

FOAM には 3 つの重要な目的があります。

  • 全周波数範囲の定義: FOAM は、サポートされている最小バイブレーション周波数と最大バイブレーション周波数を指定することで、デバイスの全周波数範囲を定義します。
  • 強度とシャープネスの値の定義: 基本 PWLE API は、強度とシャープネスの人の知覚スケールで動作し、FOAM の出力加速度値を使用してハードウェアの周波数と振幅のパラメータにマッピングされます。このマッピングにより、触覚効果がハードウェアの機能に応じてレンダリングされます。鮮明度の範囲 は、知覚可能な最小しきい値によって定義され、ユーザーが感じられる触覚効果をデバイスが生成できる周波数に対応します。フレームワークは、選択した周波数でのターゲット出力加速度に基づいて、強度値を振幅にマッピングします。これにより、デバイスの機能内で選択した強度レベルを達成できます。
  • ハードウェア機能の公開: FOAM は VibratorFrequencyProfileVibratorFrequencyProfile でデベロッパーに公開され、デバイスの触覚機能の一部を詳しく説明する、周波数から出力 加速度への完全なデータセットを提供します。 このデータを使用すると、高度な PWLE API を使用するデベロッパーは、フレームワークで定義された基本的な強度と鮮明度の範囲を超えるカスタム バイブレーション効果を作成できます。

FOAM と基本 PWLE API

FOAM は、バイブレーション効果を形成するうえで重要なロールを果たします。基本エンベロープ API の鮮明度の範囲を計算するために使用され、振動がユーザーに知覚されるようにします。この範囲は、出力加速度が人間の知覚検出のしきい値（知覚可能な最小レベル）を初めて 10 dB 上回る周波数から、出力加速度がそのしきい値を最後に上回る周波数までです。この範囲には、アクチュエータの共振周波数を含める必要があります。

また、フレームワークは FOAM データを使用して、基本 PWLE API で使用される強度と鮮明度の値を、対応する振幅と周波数の値にマッピングします。このマッピングは、さまざまなデバイスで知覚可能な触覚フィードバックを生成するのに役立ちます。

VTS テストは、エンベロープ効果をサポートするデバイスに、知覚可能な振動を生成する空でない周波数範囲があり、その範囲にアクチュエータの共振周波数が含まれていることを確認するために実施されます。これにより、デバイスはユーザーがはっきりと感じられる十分な強度の振動を生成できます。

FOAM と高度な PWLE API

FOAM は、VibratorFrequencyProfile とともに 次の情報によってデベロッパーに公開されます。

  • 周波数範囲: デベロッパーは、デバイスでサポートされている最小周波数と 最大周波数（ヘルツ単位）を、getMinFrequencyHz と getMaxFrequencyHz を使用して取得できます。
  • 最大出力加速度: デバイスで達成可能な最大出力 加速度（G 単位）は、getMaxOutputAccelerationGs で取得できます。
  • 周波数から出力加速度へのマッピング: getFrequenciesOutputAcceleration は、HAL に実装されている周波数から出力加速度へのマッピングを提供します。

デベロッパーは、高度な PWLE API を使用してエンベロープ効果を作成する際に、この情報を使用できます。たとえば、出力加速度（G 単位）を指定する場合は、デバイスの最大出力加速度を基準として、[0.0, 1.0] の範囲内の値に正規化する必要があります。

高度な PWLE API を使用すると、デベロッパーは周波数範囲全体を使用できるため、提供される FOAM データがバイブレータにとって安全で、その機能を超えないようにすることが重要です。

人間の知覚検出のしきい値

人間の知覚検出のしきい値とは、人が確実に検出できる振動の最小加速度を指します。このレベルは、振動周波数によって異なります。

次のプロットは、人間の触覚知覚検出のしきい値1（ 加速度）を時間周波数の関数として示しています。

人間の触覚認識検出のしきい値

図 2.人間の触覚知覚検出のしきい値。

ユーザーがハプティクス効果を常に感じられるように、VTS テストでは、エンベロープ機能を備えたデバイスの周波数範囲が、人間の知覚検出のしきい値を 10 dB 超えるバイブレーション振幅を生成できることを検証します。

知覚される振動の強さと振動加速度の振幅

振動の強度（知覚測定）に対する人間の知覚は、振動振幅（物理パラメータ）に比例して増加しません。PWLE API は、デザイナーまたはデベロッパーがバイブレーションの強さの変化を考える場合、知覚される強度が PWLE に従うことを想定しています。知覚される強度は、同じ周波数での検出のしきい値を超える dB として定義される感覚レベル（SL）によって特徴付けられます。したがって、振動加速度の振幅（G ピーク）は次のように計算できます。

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

ここで、振幅 dB は、特定の周波数での SL と検出のしきい値（次のプロットの縦軸の値）の合計です。

このようにして、PWLE API は、知覚される強度が連続するコントロール ポイントのペア間で線形に変化するようにします。

次のプロットは、10、20、30、 40、50 dB SL での振動加速度レベル2と、人間の触覚知覚検出 のしきい値（0 dB SL）を時間周波数の関数として示しています。

バイブレーションの加速度レベル

図 3.振動加速度レベル。

周波数から最大出力加速度への曲線を決定する

このセクションでは、デバイスから周波数から最大出力加速度への曲線を取得する一般的なガイドラインについて説明します。この曲線を使用して FOAM データを生成します。

最大電圧曲線（V）を取得する

V は、動作周波数範囲でバイブレータに安全に印加できる最大電圧です。これにより、バイブレータが安全な範囲内で動作し、損傷を防ぎ、振動出力を最大化できます。

ハードウェアに電圧制限機能がある場合は、それを使用して、サポートされている周波数範囲で達成可能な最大電圧を直接測定します。

最大加速度（M）を計算する

M は最大加速度であり、さまざまな方法で計算できます。このセクションでは、リニア共振アクチュエータ（LRA）を使用するデバイスの方法について説明します。

この方法では、特定の周波数で印加される最大電圧を、対応する最大加速度値（G ピーク）に変換します。

この変換に使用されるコア方程式は次のとおりです。

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

ここで

Vsys: 触覚アクチュエータに印加される実際の電圧レベル

BLsys：振動モーターの磁場強度（B）と導体長（L）の積

Loc_coeff: モジュール レベルの加速度をスマートフォン レベルの加速度に変換する位置係数

Rsys: 振動モーター コイルの電気抵抗

MPhone: デバイス（スマートフォンなど）の質量

w: 駆動信号の角周波数（ラジアン / 秒）。次のように計算されます。

\(w = 2 \pi f\)

Psys_abs: 2 次の質量、ダンパー、スプリング システムの振幅応答。次のように計算されます。

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

Wnsys: 振動システムの固有振動数

Qsys: 振動システムの品質係数

Loc_coeff は、スマートフォン レベルで測定された加速度とモジュール レベルで測定された加速度の比率です。この比率は、モジュール レベルの加速度の読み取り値を、同等のスマートフォン レベルの加速度の読み取り値に変換するために使用されます。スマートフォン レベルでは、モジュールの動きの角加速度により加速度が増幅されます。この係数は、その種の効果を考慮します。次のように計算されます。

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

たとえば、モジュールの加速度が 1 g、スマートフォンの加速度が 2.5 g の場合、Loc_coeff = 2.5 になります。これは 2.5 倍の増幅を示します。

Android フレームワークは周波数をヘルツ単位で取得するため、HAL は FOAM データを生成するときに、周波数の単位をラジアン / 秒からヘルツに変換する必要があります。

FOAM 曲線を生成する

最大電圧曲線（V）と加速度の計算（M）を組み合わせて、FOAM 曲線を決定します。

  • 目的の範囲内の各周波数（f）について、対応する 最大電圧V(f)を最大電圧曲線から見つけます。
  • 上記の方程式 を使用して、その周波数での最大加速度を計算します。Vsys に V(f) を代入し、w に対応する f を代入します。 これにより、M(V(f), f) が得られます。
  • 計算された加速度が FOAM(f) 値になります。

FOAM データを公開する

FOAM 曲線が生成されると、HAL は曲線を FrequencyAccelerationMapEntry オブジェクトのリストとして表します。各エントリはマッピング内のポイントを定義し、周波数（ヘルツ単位）とその対応する最大出力加速度（G ピーク）を指定します。

中間加速度値を決定する際の線形補間の精度を最適化するには、最大出力加速度の周波数付近で高い周波数分解能を定義することをおすすめします。たとえば、この周波数の +/- 10 Hz の範囲内で 1 Hz 刻みを使用します。

デバイスの機能と制限事項

Android 16 以降では、デベロッパーが PWLE 効果を最適化し、デバイス間の互換性を確保できるように、Android にはデバイスの PWLE 機能をクエリするための HAL API が含まれています。これらのメソッドは、最小または最大の PWLE プリミティブ期間や、PWLE 構成で許可されるプリミティブの数など、デバイスの制限に関する情報を提供します。

HAL API には次のものがあります。

  • CAP_COMPOSE_PWLE_EFFECTS_V2: デバイスがこの機能をサポートしている場合、IVibrator.getCapabilities によって返されます。
  • getFrequencyToOutputAccelerationMap: FOAM データを取得します。
  • getPwleV2PrimitiveDurationMinMillis: プリミティブ PWLE に許可される最小期間をミリ秒単位で取得します。
  • getPwleV2PrimitiveDurationMaxMillis: プリミティブ PWLE に許可される最大期間をミリ秒単位で取得します。
  • getPwleV2CompositionSizeMax: IVibrator.composePwleV2 でサポートされている PWLE プリミティブの最大数を取得します。

この情報はデベロッパーに公開され、特に高度な PWLE API を使用する場合に、対象デバイスの特定の機能に合わせて効果を調整できます。

フレームワークは、基本 API で作成された効果を処理する際にもこれらの API を使用します。効果がデバイスの制限を超える場合（PWLE ポイントが多すぎる、期間が最大値を超えるなど）、フレームワークは許可された範囲内に収まるように効果を自動的に調整します。この調整プロセスでは、デザインの元の意図と感覚を可能な限り維持しようとします。

  1. しきい値データは、Bolanowski Jr. の図 1 の変位 しきい値から変換されています。S. J. 他。「Four channels mediate the mechanical aspects of touch.」Journal of the Acoustical Society of America 84(5): 1680-1694 (1988)。この オンライン チュートリアルでは、加速度 振幅と変位振幅の変換について説明しています。 ↩

  2. このデータは、Verrillo, R. の図 8 から推定されています。T. 他。「Sensation magnitude of vibrotactile stimuli.」 Perception &Psychophysics 6: 366-372 (1969)。 ↩