このページでは、公開 HAL 定数と API 定数の間の推奨されるマッピングを示します。評価したハードウェアが HAL 定数を実装していない場合は、定数とプリミティブを実装するページに記載されたフォールバック パターンを更新して、同様の出力を生成します。マッピングは、2 つの異なるデフォルト モデルによって支援されます。
このモデルの主な変数はテクスチャと振幅です。HAL の各エンティティは異なる触覚テクスチャを表します。各 HAL エンティティの振幅は、スケーリング ファクタ(S)によって制御されます。
このモデルには高度なハードウェアが必要です。OEM が最新のハプティクス API を最大限活用するために、VibrationEffect.Composition で高度な触覚 UX を使用する場合は、このモデルを使用してハードウェアを実装することをおすすめします。
非連続モデル
API で提供されるすべてのパブリック定数を、適切な HAL 定数にマッピングすることをおすすめします。このプロセスを開始するには、デバイスが HAL で定義できる、非連続の振幅を持つ触覚波形の数を確認します。この概念に基づいた具体的な質問は次のようになります。「1 台のスマートフォンに、人間が知覚できる振幅差を持つシングル インパルス触覚衝撃をいくつ定義できますか?」この質問に対する回答によってマッピングが決まります。
HAL 定数の定義はハードウェアに依存するプロセスです。たとえば、エントリー レベルのスマートフォンには、単一の触覚波形を生成するハードウェア機能しかないことがあります。より高度なハードウェア コンポーネントを備えたデバイスでは、より広範囲な非連続の振幅レベルが生成され、HAL で複数の触覚波形を定義できます。HAL - API 定数マッピングでは、HAL 定数を(中程度の振幅をベースラインに)使用して、より強い、またはより弱い効果を合成します。
図 14. 振幅による HAL 定数の範囲
非連続の振幅を持つ HAL 定数の数を定義したら、HAL 定数と API 定数を HAL 定数の数でマッピングします。このマッピング プロセスでは、シングル インスパルス API 定数を、最大 3 つの振幅レベルの非連続なグループに分割できます。API 定数をセグメント化する方法は、付随する入力イベントの UX 原則に基づきます。詳しくは、ハプティクス UX デザインをご覧ください。
図 15. HAL - API 定数マッピング: 非連続モデル
デバイスが、非連続の振幅を持つ 2 つの HAL 定数のみをサポートしている場合は、中振幅レベルと高振幅レベルの HAL 定数を統合することを検討してください。この概念の実例としては、EFFECT_CLICK と EFFECT_HEAVY_CLICK を同じ HAL 定数(中振幅レベルの HAL 定数)にマッピングすることが挙げられます。デバイスが、非連続の振幅を持つ 1 つの HAL 定数のみをサポートしている場合は、3 つのレベルをすべて 1 つに統合することを検討してください。
連続モデル
振幅スケーラビリティがある連続モデルは、HAL 定数を定義するために適用できます。スケーリング ファクタ(S)を HAL 定数(HAL_H0、HAL_H1 など)に適用して、スケールされた HAL(HAL_H0 × S)を生成できます。この場合、図 16 に示すように、スケールされた HAL は API 定数(HAL_H0 × S1 = H0S1 = EFFECT_TICK)を定義するためにマッピングされます。連続モデルの振幅スケーラビリティを使用することで、デバイスは固有のテクスチャを持つ少数の HAL 定数を格納でき、スケーリング ファクタ(S)を調整することで振幅の変動を追加できます。デバイス メーカーは、提供するさまざまな触覚テクスチャの数に基づいて HAL 定数の数を定義できます。
図 16. テクスチャ(HAL_H0)と振幅スケール(S)による HAL 定数の範囲
図 17. HAL - API 定数マッピング: 連続モデル
連続モデルでは、異なる HAL 定数は、異なる振幅ではなく、異なる触覚テクスチャを表します。スケーリング ファクタ(S)で振幅を設定できます。ただし、テクスチャの認識(シャープネスなど)は持続と振幅の認識に関係するため、テクスチャとスケーリング ファクタを組み合わせることをおすすめします(HAL - API マッピングの設計プロセス)。
図 18 は、振幅スケーラビリティによって 1 つの 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-03-10 UTC。"],[],[],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*."]]