이 페이지에서는 공개 HAL 상수와 API 상수 간의 권장 매핑을 제시합니다. 평가된 하드웨어가 HAL 상수를 구현하지 않는 경우 상수 및 프리미티브 구현 페이지에 설명된 대체 패턴을 업데이트하여 유사한 출력을 생성합니다. 매핑은 다음과 같은 두 가지 기본 모델에 의해 지원됩니다.
질감 및 진폭은 이 모델의 핵심 변수입니다. HAL의 각 항목은 서로 다른 햅틱 질감을 나타냅니다. 각 HAL 항목의 진폭은 배율 (S)로 제어됩니다.
이 모델에는 고급 하드웨어가 필요합니다. OEM이 VibrationEffect.Composition과 함께 고급 햅틱 UX를 사용하려는 경우(최신 햅틱 API를 최대한 활용하기 위해) 이 모델을 사용하여 하드웨어를 구현하는 것이 좋습니다.
불연속 모델
API에서 제공하는 모든 공개 상수를 적절한 HAL 상수와 매핑하는 것이 좋습니다. 이 프로세스를 시작하려면 기기가 HAL에서 정의할 수 있는 불연속 진폭이 있는 햅틱 파형 수를 알아보세요. 이 개념을 중심으로 구성된 구체적인 질문은 다음과 같습니다. 즉, 내 휴대전화에서 사람이 감지할 수 있는 진폭 차이가 있는 단일 임펄스 햅틱 효과를 몇 개나 정의할 수 있나요? 이 질문에 대한 답을 통해 매핑이 결정됩니다.
HAL 상수 정의는 하드웨어에 종속되는 프로세스입니다. 예를 들어 보급형 휴대전화에는 단일 햅틱 파형을 생성하는 하드웨어 기능만 있을 수 있습니다. 고급 하드웨어 구성요소가 있는 기기는 더 광범위한 불연속 진폭 수준을 생성하고 HAL에서 여러 햅틱 파형을 정의할 수 있습니다. HAL-API 상수 매핑은 HAL 상수를 사용(중간 진폭을 기준으로 사용)한 후 여기에서 더 강하거나 약한 효과를 준비합니다.
그림 14. 진폭에 따른 HAL 상수 범위
불연속 진폭이 있는 HAL 상수의 수를 정의했다면 이제 HAL 상수의 수에 따라 HAL 상수와 API 상수를 매핑할 차례입니다. 이 매핑 프로세스에서는 단일 임펄스 API 상수를 최대 3개의 불연속 진폭 수준 그룹으로 분류할 수 있습니다. API 상수를 분류하는 방식은 함께 제공되는 입력 이벤트에 관한 UX 원칙을 기반으로 합니다. 자세한 내용은 햅틱 UX 디자인을 참고하세요.
그림 15. HAL-API 상수 매핑: 불연속 모델
기기가 불연속 진폭이 있는 HAL 상수를 2개만 지원한다면 중간 및 높은 진폭 수준의 HAL 상수를 병합하는 것이 좋습니다. 실제로 이 개념의 예는 EFFECT_CLICK 및 EFFECT_HEAVY_CLICK을 동일한 HAL 상수(중간 진폭 수준의 HAL 상수)에 매핑하는 것입니다. 기기가 불연속 진폭이 있는 HAL 상수를 하나만 지원한다면 세 수준을 모두 하나로 병합하는 것이 좋습니다.
연속 모델
진폭 확장성이 있는 연속 모델을 적용하여 HAL 상수를 정의할 수 있습니다. 배율 (S)을 HAL 상수 (예: HAL_H0, HAL_H1)에 적용하여 확장된 HAL (HAL_H0 x S)을 생성할 수 있습니다. 이 경우 그림 16과 같이 확장된 HAL을 매핑하여 API 상수 (HAL_H0 x S1 = H0S1 = EFFECT_TICK)를 정의할 수 있습니다. 연속 모델의 진폭 확장성을 사용하면 기기는 고유한 질감이 있는 소수의 HAL 상수를 저장하고 배율(S)을 조정하여 진폭 변형을 추가할 수 있습니다. 기기 제조업체는 제공하려는 다양한 햅틱 질감의 수에 따라 HAL 상수의 수를 정의할 수 있습니다.
그림 16. 질감(HAL_H0) 및 진폭 배율(S)에 따른 HAL 상수 범위
그림 17. HAL-API 상수 매핑: 연속 모델
연속 모델에서 서로 다른 HAL 상수는 서로 다른 진폭이 아닌 서로 다른 햅틱 질감을 나타냅니다. 배율(S)은 진폭을 구성할 수 있습니다. 그러나 질감 감지(예: 예민성)는 지속 시간 및 진폭의 감지와 관련이 있으므로 HAL-API 매핑의 디자인 프로세스에서 질감과 배율을 조합하는 것이 좋습니다.
그림 18에서는 상수 매핑을 보여줍니다. 진폭 확장성을 통해 하나의 HAL에서 여러 API 상수로 변화량을 증가시킵니다.
그림 18. 진폭 확장성을 통해 변화량 증가
VibrationEffect.Composition의 PRIMITIVE_TICK 및 PRIMITIVE_CLICK과 같이 확장 가능한 모든 API 상수의 경우 API 상수의 에너지 수준은 API 상수가 addPrimitive(int primitiveID, float scale,
int delay)를 통해 선언될 때의 float scale 매개변수에 따라 달라집니다. PRIMITIVE_TICK 및 PRIMITIVE_CLICK은 서로 다른 HAL 상수를 사용함으로써 명확하게 구분하여 디자인할 수 있습니다. 이 접근 방식은 질감에 변화량을 추가하려는 경우에 권장됩니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[[["이해하기 쉬움","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(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*."]]
