建议将该 API 中提供的所有公共常量与相应的 HAL 常量进行映射。如需开始此过程，请了解设备可以在 HAL 中指定多少个具有离散振幅的触感反馈波形。围绕该概念产生的具体问题类似于：我的手机中可以指定多少个具有人类可感知的振幅差异的单脉冲触感反馈效果？此问题的答案决定了需要执行的映射。
指定 HAL 常量的过程依赖于硬件。例如，入门级手机的硬件功能可能只能产生单个触感反馈波形。配备更高级硬件组件的设备可以产生更广泛的离散振幅级别，并在 HAL 中指定多个触感反馈波形。在进行 HAL-API 常量映射时，需要先选取 HAL 常量（使用中等振幅作为基准），然后以此为基础安排更强或更弱的效果。
图 14. HAL 常量范围（按振幅）
指定具有离散振幅的 HAL 常量的数量之后，就该按 HAL 常量的数量映射 HAL 和 API 常量了。此映射过程最多可将一个单脉冲 API 常量细分为三组离散的振幅级别。API 常量的细分方式以伴随的输入事件的用户体验原则为基础。如需了解详情，请参阅触感反馈用户体验设计。
图 15. HAL-API 常量映射：离散模型
如果您的设备仅支持两个具有离散振幅的 HAL 常量，请考虑合并“中”和“高”振幅级别的 HAL 常量。在实践中，此概念的一个示例为：将 EFFECT_CLICK 和 EFFECT_HEAVY_CLICK 映射到同一 HAL 常量，这会是“中”振幅级别 HAL 常量。如果您的设备仅支持一个具有离散振幅的 HAL 常量，请考虑将所有三个级别合并为一个。
连续模型
可以通过应用具有振幅调节功能的连续模型来指定 HAL 常量。可将调节系数 (S) 应用于 HAL 常量（例如，HAL_H0 和 HAL_H1），以便生成经过调节的 HAL 常量 (HAL_H0 x S)。在本示例中，经过调节的 HAL 会进行映射，以指定 API 常量 (HAL_H0 x S1 = H0S1 = EFFECT_TICK)，如图 16 所示。通过使用连续模型的振幅调节功能，设备可以存储具有独特纹理的少量 HAL 常量，并通过调整调节系数 (S) 来添加振幅变体。设备制造商可以根据自己想要提供的不同触感反馈纹理的数量来指定 HAL 常量的数量。
图 16. HAL 常量范围（按纹理 [HAL_H0] 和振幅比例 [S]）
图 17. HAL-API 常量映射：连续模型
在连续模型中，不同的 HAL 常量表示不同的触感反馈纹理，而不是不同的振幅；调节系数 (S) 可以配置振幅。但是，由于对纹理的感知（例如，清晰度）与对持续时间和振幅的感知有关，因此建议在 HAL-API 映射的设计过程中将纹理和调节系数结合使用。
图 18 展示了利用振幅调节功能，通过增加变体将一个 HAL 常量映射到多个 API 常量的过程。
图 18. 利用振幅调节功能增加变体
对于所有可调节的 API 常量（例如 VibrationEffect.Composition 中的 PRIMITIVE_TICK 和 PRIMITIVE_CLICK），其能量等级取决于通过 addPrimitive(int primitiveID, float scale,
int delay) 声明该常量时的 float scale 参数。通过使用不同的 HAL 常量，可以在设计 PRIMITIVE_TICK 和 PRIMITIVE_CLICK 时做出明确的区分。如果要添加纹理变体，建议使用此方法。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-03-10。"],[],[],null,["# Map constants between HAL and API\n\nThis page presents recommended mappings between public HAL constants and API\nconstants. If the hardware assessed doesn't implement the HAL constants, then\nupdate the fallback patterns described in [Implement constants and primitives](/docs/core/interaction/haptics/haptics-constants-primitives#implement-constants-and-primitives)\npage to generate similar outputs. The mapping is assisted by two different\ndefault models:\n\n- [Discrete model](#discrete-model) (simple)\n\n - Amplitude is the key variable of this model. Each entity in the HAL represents a different haptic amplitude.\n - This model is a minimum requirement needed to implement the basic haptic UX.\n - A more advanced haptic UX requires advanced hardware and an advanced model (continuous model).\n- [Continuous model](#continuous-model) (advanced)\n\n - Texture and amplitude are the key variables of this model. Each entity in the HAL represents different haptic textures. The amplitude of each HAL entity is controlled by the scale factor (`S`).\n - This model requires advanced hardware. If OEMs want to use advanced haptic UX with [`VibrationEffect.Composition`](https://developer.android.com/reference/android/os/VibrationEffect.Composition) (for the best use of the latest haptics APIs), implementing their hardware using this model is recommended.\n\nDiscrete model\n--------------\n\nMapping all public constants provided in the API with appropriate HAL constants\nis recommended. To begin this process, find out how many haptic waveforms with\ndiscrete amplitude the device can define in the HAL. A specific question\nstructured around that notion looks like this: *How many single-impulse haptic\neffects with human-perceptible amplitude differences can be defined in my\nphone?* The answer to this question determines the mapping.\n\nDefining HAL constants is a hardware-dependent process. For example, an\nentry-level phone might have only the hardware capabilities to produce a single\nhaptic waveform. Devices with more advanced hardware components produce a wider\nrange of discrete amplitude levels, and can define multiple haptic waveforms in\nthe HAL. HAL-API constant mapping takes the HAL constant (using the medium\namplitude as a baseline), then arranges stronger or weaker effects from there.\n\n**Figure 14.** HAL constant range by amplitude\n\nWhen the number of HAL constants with discrete amplitude is defined, it's time\nto map HAL and API constants by the number of HAL constants. This mapping\nprocess can segment a single impulse API constant into up to three discrete\ngroups of amplitude levels. The way that API constants are segmented is based on\nUX principles for accompanying input events. For more information, see [Haptics\nUX design](/docs/core/interaction/haptics/haptics-ux-design).\n\n**Figure 15.** HAL-API constant mapping: Discrete model\n\nIf your device supports only two HAL constants with discrete amplitudes,\nconsider merging Medium and High amplitude level HAL constants. An example of\nthis notion in practice would be mapping `EFFECT_CLICK` and `EFFECT_HEAVY_CLICK`\nto the same HAL constant, which would be the Medium amplitude level HAL\nconstant. If your device supports only *one* HAL constant with discrete\namplitude, consider merging all three levels into one.\n\nContinuous model\n----------------\n\nThe continuous model with amplitude scalability can be applied to define HAL\nconstants. A scale factor (`S`) can be applied to the HAL constants (for\nexample, `HAL_H0`, `HAL_H1`) to produce the scaled HAL (`HAL_H0` x `S`). In this\ncase, the scaled HAL is mapped to define API constants (`HAL_H0` x `S1` = `H0S1`\n= `EFFECT_TICK`) as shown in figure 16. By using amplitude scalability of the\ncontinuous model, a device can store a small number of HAL constants with\ndistinctive textures and add amplitude variations by adjusting the scale factor\n(`S`). Device manufacturers can define the number of HAL constants based on how\nmany different haptic textures they want to provide.\n\n**Figure 16.** HAL constant range by texture (HAL_H0) and amplitude scale (S)\n\n**Figure 17.** HAL-API constant mapping: Continuous model\n\nIn the continuous model, different HAL constants represent different haptic\n*textures* rather than different amplitudes; the scale factor (`S`) can\nconfigure the amplitude. However, because the perception of the texture (for\nexample, sharpness) is related to the perception of the duration and amplitude,\ncombining the texture and the scale factor (in the design process of HAL-API\nmapping) is recommended.\n\nFigure 18 illustrates constant mapping by increasing variation from one HAL to\nmany API constants with amplitude scalability.\n\n**Figure 18.** Increasing variation with amplitude scalability\n| **Note:** The Figure 18 illustrates a specific instance of constant mapping, so the naming conventions are hypothetical. Performing this process is unique for each device manufacturer.\n\nFor all scalable API constants such as `PRIMITIVE_TICK` and `PRIMITIVE_CLICK` in\n[`VibrationEffect.Composition`](https://developer.android.com/reference/android/os/VibrationEffect.Composition),\nthe energy level of the API constant depends on the `float scale` parameter when\nthe API constant is declared through `addPrimitive(int primitiveID, float scale,\nint delay)`. `PRIMITIVE_TICK` and `PRIMITIVE_CLICK` can be designed with a clear\ndistinction by using different HAL constants. This approach is recommended if\nyou want to add variation to *texture*."]]
