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

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

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

• 基本的な PWLE API: シンプルですが、制限があります。すぐに使い始めるのに適しています。BasicEnvelopeBuilder で確認できます。
• Advanced 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 ms と、PWLE 効果に少なくとも 16 個のポイントを処理できる必要があります。これらの要件は VTS テストによって適用され、Android デバイス全体で信頼性の高い PWLE 効果を確保します。

Advanced PWLE API

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

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

以下に、バイブレーターをオフから 120 Hz で 100 ms かけてフル振幅まで増加させ、その状態を 200 ms 保持してから 100 ms かけて元に戻す波形の例を示します。

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

制約

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

デベロッパーは、PWLE エフェクトで指定された周波数が、デバイスの FOAM で定義されているデバイスのサポート範囲内であることを確認する必要があります。値がこれらの上限を超えると、デバイスは振動を再生しません。

出力加速度と周波数のマッピング（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 に従うことを前提としています。知覚される音量は、感覚レベル（SL）で表されます。これは、同じ周波数で検出しきい値を超える dB として定義されます。したがって、振動加速度の振幅（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 効果を最適化し、デバイス間の互換性を確保できるように、デバイスの PWLE 機能をクエリするための HAL API が Android に含まれています。これらのメソッドは、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 ポイントが多すぎる、または時間が最大時間を超過しているなど）、フレームワークは、許容範囲内に収まるようにエフェクトを自動的に調整します。この調整プロセスでは、デザインの元の意図と雰囲気を可能な限り維持するよう努めています。