实现分段线性封套效果

分段线性封装容器 (PWLE) 效果是一系列点，用于定义振动频率和随时间变化的加速度。PWLE 可提供更丰富、更动态的触感反馈。

Android 16 及更高版本提供了两个应用开发者 API 来帮助创建 PWLE 效果：

• 基本 PWLE API：简单，但有限制。适合快速上手。您可以访问 BasicEnvelopeBuilder 查看此信息。
• 高级 PWLE API：可提供更高的控制力和灵活性，但需要具备触感反馈方面的知识，并对硬件有所了解。可在 WaveformEnvelopeBuilder 找到。

如需支持这些 API，设备必须实现以下 HAL API：

• 频率到输出加速度映射 (FOAM)：提供振动频率与设备可实现的最大输出加速度的映射。
• Compose PWLE：播放由振动波形的 PWLE 定义的振动。

基本 PWLE API

如需快速创建 PWLE 效果，而无需深入了解硬件或人类感知的细微之处，开发者可以使用使用以下参数定义的基本 PWLE API：

• 强度值介于 [0, 1] 之间，表示振动感知强度。例如，值 0.5 被视为设备可实现的全球最大强度的 1/2。
• 锐度值介于 [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 点之间的最短时长为 10 毫秒，并且 PWLE 效果至少有 16 个点。这些要求由 VTS 测试强制执行，有助于确保在各种 Android 设备上获得可靠的 PWLE 效果。

Advanced PWLE API

对触感反馈有深入了解的开发者可以使用以下条件定义 PWLE 效果：

• 振幅值介于 [0, 1] 之间，表示在给定频率下可实现的信号强度，由设备 FOAM 决定。例如，值 0.5 会产生在给定频率下可实现的最大输出加速度的一半。
• 频率直接以赫兹为单位指定。
• 时长是从上一个 PWLE 点转换到新 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 振幅的起始点，以确保平滑过渡。

开发者有责任确保其 PWLE 效果中指定的频率在设备支持的范围内（如设备的 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 分贝。

感知到的振动强度与振动加速度振幅

人对振动强度的感知（一种感知测量）不会随着振幅（一种物理参数）线性增加。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) 的设备的一种方法。

此方法可将给定频率下的最大施加电压转换为相应的最大加速度值（以峰值 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 包含用于查询设备 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 点过多或时长超出上限），框架会自动调整该效果，使其符合允许的边界。此调整流程会尽可能保留设计的原始意图和风格。