實作區域線性包絡效果

分段線性包絡函數 (PWLE) 效果是一系列點，定義振動頻率和加速度隨時間變化。PWLE 提供更豐富、更動態的觸覺回饋。

Android 16 以上版本提供兩個應用程式開發人員 API，可協助建立 PWLE 效果：

• 基本 PWLE API：簡單，但有限制。適合快速入門。這項功能可在 BasicEnvelopeBuilder 中使用。
• 進階 PWLE API：提供更多控制選項和彈性，但需要具備觸覺技術知識，並對硬體稍有瞭解。可在 WaveformEnvelopeBuilder 下載。

如要支援這些 API，裝置必須實作下列 HAL API：

• 頻率至輸出加速度對應 (FOAM)：提供振動頻率與裝置可達到的最大輸出加速度的對應關係。
• Compose PWLE：播放由震動波形的 PWLE 定義的震動。

基本 PWLE API

如要快速建立 PWLE 效果，而無須深入瞭解硬體或人類感知的細微差異，開發人員可以使用基本 PWLE API，並使用下列參數定義：

• Intensity 值介於 [0, 1] 之間，代表振動的感知強度。舉例來說，0.5 值會被視為裝置可達到的全球最大強度的一半。
• Sharpness 值介於 [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 效果。

進階 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 振幅起點，確保順暢的轉換。

開發人員有責任確保 PWL 特效中指定的頻率落在裝置支援的範圍內，這由裝置的 FOAM 定義。如果值超過這些限制，裝置「不會」播放任何震動。

頻率至輸出加速度對應 (FOAM)

如要支援 PWLE API，就必須準確呈現裝置的頻率輸出加速度功能。本節將詳細說明這類資料的重要性、PWLE API 如何使用這類資料，以及產生這類資料的程序。

瞭解對應

支援 PWLE 效果的裝置需要提供頻率輸出加速度地圖 (FOAM)。FOAM 是由 HAL 產生的資料結構，可將振動頻率 (以赫茲為單位) 對應至執行器在該頻率下可達到的最大輸出加速度 (以 G 峰值為單位)。如要瞭解支援頻率範圍的震動輸出變化情形，以及定義基本 PWLE API，這份對應表就非常重要。

下圖為典型諧振致動器的 FOAM 範例，其中輸入電壓會在諧振頻率附近受到限制，以保護馬達：

圖 1. 典型諧振致動器的 FOAM 示例。

FOAM 有三個主要用途：

• 定義完整頻率範圍：FOAM 會指定支援的最小和最大振動頻率，藉此定義裝置的完整頻率範圍。
• 定義強度和清晰度值：基本 PWLE API 會根據人類感知的強度和清晰度等級運作，然後使用 FOAM 中的輸出加速度值，將這些值對應至硬體頻率和振幅參數。這項對應功能可確保觸覺效果會根據硬體功能算繪。清晰度範圍是由最小可感知門檻定義，並對應裝置可產生使用者可感知的觸覺效果的頻率。此架構會根據所選頻率的目標輸出加速度，將強度值對應至振幅。這有助於確保在裝置能力範圍內，達到所選強度等級。
• 公開硬體功能：FOAM 會在 VibratorFrequencyProfile 中公開給開發人員，提供完整的頻率輸出加速度資料集，詳細說明裝置的部分觸覺回饋功能。這項資料可讓使用進階 PWLE API 的開發人員建立自訂震動效果，超越架構定義的基本強度和清晰度範圍。

FOAM 和基本 PWLE API

FOAM 在塑造震動效果方面扮演重要角色。用於計算基本包絡函式 API 的銳利度範圍，確保使用者能感受到震動。這個範圍對應的頻率，是指輸出加速度高於每個頻率人類感知偵測門檻 (即最小可感知等級) 的 10 dB 以上。這麼做可確保震動強度足以讓使用者感受到震動。

此外，架構會使用 FOAM 資料，將基本 PWLE API 中使用的強度和銳利度值對應至相應的振幅和頻率值。這項對應功能有助於在不同裝置上產生可感知的觸覺回饋。

VTS 測試可確保支援封套效果的裝置具有非空頻率範圍，可產生可感知的震動。這有助於確保裝置能產生足夠強度的震動，讓使用者清楚感受到震動。

FOAM 和進階 PWLE API

VibratorFrequencyProfile 會將 FOAM 提供給開發人員，並提供以下資訊：

• 頻率範圍：開發人員可以分別使用 getMinFrequencyHz 和 getMaxFrequencyHz，擷取裝置支援的最低和最高頻率 (以赫茲為單位)。
• 最大輸出加速度：透過 getMaxOutputAccelerationGs 可取得裝置可達到的最大輸出加速度 (以 G 為單位)。
• 頻率至輸出加速度對應： getFrequenciesOutputAcceleration 會提供頻率至輸出加速度對應，如 HAL 中所實作。

開發人員可在使用進階 PWLE API 建立包絡效果時使用這項資訊。舉例來說，在指定輸出加速度 (以 G 為單位) 時，必須將其正規化為介於 [0.0, 1.0] 範圍內的值，以便與裝置的最大輸出加速度進行比較。

有了進階的 PWLE API，開發人員就能使用整個頻率範圍，因此提供的 FOAM 資料必須對震動器安全，且不會超出其能力。

人類感知偵測門檻

人類感知偵測門檻是指人類可可靠偵測到的振動最小加速度。這項等級會因震動頻率而異。

下列圖表顯示人類觸覺感知偵測門檻¹，以加速度為單位，做為時間頻率的函式：

圖 2. 人類觸覺感知偵測門檻。

為了讓使用者能持續感受到觸覺回饋效果，VTS 測試會驗證具備包絡功能的裝置，其頻率範圍可產生振動幅度，超過人類感知偵測閾值 10 dB。

感知到的震動強度與震動加速度幅值

人類對振動強度的感知 (感知評估) 並不會隨著振動幅度 (物理參數) 線性增加。PWLE API 假設設計人員或開發人員在考慮震動強度變化時，會預期感知強度會遵循 PWLE。感知強度以感知音量 (SL) 為特徵，其定義為在相同頻率下，高於偵測閾值的分貝數值。因此，振動加速度幅度 (以 G 峰值為單位) 的計算方式如下：

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

其中振幅分貝是特定頻率下 SL 和偵測閾值 (下圖中沿著垂直軸的值) 的總和。

如此一來，PLWE API 就能確保在連續控制點組之間，感知強度會以線性方式變化。

下圖顯示 10、20、30、40 和 50 dB SL 的震動加速度等級²，以及人類觸覺感知偵測閾值 (0 dB SL)，以時間頻率為函數。

圖 3. 震動加速度等級。

判斷頻率至最大輸出加速曲線

本節提供一般指南，說明如何從裝置取得頻率至最大輸出加速度的曲線，以產生 FOAM 資料。

取得最大電壓曲線 (V)

V 是指在振動器的運作頻率範圍內，可安全施加的最大電壓。這可確保震動器在安全範圍內運作，避免損壞並提高震動輸出量。

如果硬體包含電壓限制功能，請使用該功能直接測量支援頻率範圍內可達到的最高電壓。

計算最大加速度 (M)

M 是最大加速度，您可以透過各種方法計算。本節將說明使用線性諧振致動器 (LRAs) 的裝置所適用的方法。

這個方法會將特定頻率的最大施加電壓轉換為對應的最大加速度值，以 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：二次質量、阻尼器和彈簧系統的振幅回應，計算方式如下：

\(\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)。
• 使用上述方程式計算該頻率的最大加速度，將 V(f) 替換為 Vsys，並將對應的 f 替換為 w。這會產生 M(V(f), f)。
• 這個計算加速度就是 FOAM(f) 值。

公開 FOAM 資料

產生 FOAM 曲線後，HAL 會將曲線表示為 FrequencyAccelerationMapEntry 物件的清單。每個項目都會定義對應的點，指定頻率 (以赫茲為單位) 及其對應的最大輸出加速度 (以 G 峰值為單位)。

雖然 FOAM 的解析度沒有嚴格規定，但我們建議您定義曲線時，只使用一個最高峰值。在基本包絡函式 API 中，只有第一個峰值會用來對應震動效果。為在判斷中間加速度值時，盡可能提高線性內插的精確度，建議您在峰值附近定義高頻率解析度。舉例來說，請使用峰值頻率 +/- 10 Hz 範圍內的 1 Hz 步進值。

裝置功能和限制

針對 Android 16 以上版本，為了協助開發人員最佳化 PWLE 效果並確保各裝置的互通性，Android 包含 HAL API，可用於查詢裝置的 PWLE 功能。這些方法會提供裝置限制的相關資訊，例如 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 點太多或時間長度超過上限)，架構會自動調整特效，使其符合允許的範圍。這個調整程序會盡可能保留設計的原始意圖和感受。