建議您將 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_H0) 和振幅縮放比例 (S) 設定 HAL 常數範圍
圖 17. HAL-API 常數對應：連續模式
在連續模型中，不同的 HAL 常數代表不同的觸覺紋理，而非不同的振幅；縮放比例 (S) 可設定振幅。不過，由於紋理感知 (例如清晰度) 與時間和振幅感知相關，因此建議在 HAL API 對應的設計過程中，結合紋理和縮放比例。
圖 18 說明常數對應，從一個 HAL 到多個 API 常數，並增加振幅可擴展性。
圖 18. 利用振幅擴展功能增加變化
對於所有可調整的 API 常數 (例如 VibrationEffect.Composition 中的 PRIMITIVE_TICK 和 PRIMITIVE_CLICK)，如果 API 常數是透過 addPrimitive(int primitiveID, float scale,
int delay) 宣告，則 API 常數的能量等級會取決於 float scale 參數。PRIMITIVE_TICK 和 PRIMITIVE_CLICK 可使用不同的 HAL 常數進行設計，以便清楚區分。如果您想為紋理新增變化，建議採用這種做法。
[[["容易理解","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"]],["上次更新時間：2025-07-27 (世界標準時間)。"],[],[],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*."]]
