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

区分的線形エンベロープ（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] の範囲の鮮明度の値は、バイブレーションの鮮明度を表します。値が小さいほど振動が滑らかになり、値が大きいほど振動が鋭くなります。
• Duration は、最後の 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 ポイント間の最小期間 10 ミリ秒と、PWLE 効果の少なくとも 16 ポイントを処理できることがフレームワークで求められています。これらの要件は VTS テストによって適用され、Android デバイス全体で信頼性の高い PWLE 効果を確保するのに役立ちます。

Advanced PWLE API

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

• [0, 1] の範囲の振幅値は、デバイスの FOAM によって決定された、特定の周波数で達成可能な強度を表します。たとえば、値が 0.5 の場合、指定された周波数で達成可能な最大出力加速度の半分が生成されます。
• 周波数はヘルツ単位で直接指定します。
• Duration は、最後の 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 の例を示しています。入力電圧は、モーターを保護するために共振周波数付近で制限されています。

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

FOAM には、次の 3 つの主な目的があります。

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

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

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

次のプロットは、人間の触覚認識の検出閾値¹を、時間周波数の関数として加速度で示しています。

図 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 での振動加速度レベル²と、人間の触覚認識検出のしきい値（0 dB SL）を、時間周波数の関数として示しています。

図 3. バイブレーションの加速度レベル。

周波数から最大出力までの加速度曲線を確認する

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

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

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

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

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

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

このメソッドは、特定の周波数での最大印加電圧を、対応する最大加速度値（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 ピーク単位）を指定します。

FOAM の解像度に関する厳格な要件はありませんが、最大ピークが 1 つの曲線で定義することをおすすめします。基本的なエンベロープ API では、バイブレーション効果をマッピングするために最初のピークのみが使用されます。中間加速度値を決定する際の線形補間の精度を最適化するには、ピーク付近で高い周波数分解能を定義することをおすすめします。たとえば、ピーク周波数の +/- 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 ポイントが多すぎる、期間が最大値を超えるなど）、フレームワークは効果を自動的に調整して、許容範囲内に収めます。この調整プロセスでは、デザインの元の意図と雰囲気を可能な限り維持しようとします。