Map constants between HAL and API

This page presents recommended mappings between public HAL constants and API constants. If the hardware assessed doesn't implement the HAL constants, then update the fallback patterns described in Implement constants and primitives page to generate similar outputs. The mapping is assisted by two different default models:

• Discrete model (simple)

  • Amplitude is the key variable of this model. Each entity in the HAL represents a different haptic amplitude.
  • This model is a minimum requirement needed to implement the basic haptic UX.
  • A more advanced haptic UX requires advanced hardware and an advanced model (continuous model).

• Continuous model (advanced)

  • 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).
  • This model requires advanced hardware. If OEMs want to use advanced haptic UX with VibrationEffect.Composition (for the best use of the latest haptics APIs), implementing their hardware using this model is recommended.

Discrete model

Mapping all public constants provided in the API with appropriate HAL constants is recommended. To begin this process, find out how many haptic waveforms with discrete amplitude the device can define in the HAL. A specific question structured around that notion looks like this: How many single-impulse haptic effects with human-perceptible amplitude differences can be defined in my phone? The answer to this question determines the mapping.

Defining HAL constants is a hardware-dependent process. For example, an entry-level phone might have only the hardware capabilities to produce a single haptic waveform. Devices with more advanced hardware components produce a wider range of discrete amplitude levels, and can define multiple haptic waveforms in the HAL. HAL-API constant mapping takes the HAL constant (using the medium amplitude as a baseline), then arranges stronger or weaker effects from there.

Figure 14. HAL constant range by amplitude

When the number of HAL constants with discrete amplitude is defined, it's time to map HAL and API constants by the number of HAL constants. This mapping process can segment a single impulse API constant into up to three discrete groups of amplitude levels. The way that API constants are segmented is based on UX principles for accompanying input events. For more information, see Haptics UX design.

Figure 15. HAL-API constant mapping: Discrete model

If your device supports only two HAL constants with discrete amplitudes, consider merging Medium and High amplitude level HAL constants. An example of this notion in practice would be mapping EFFECT_CLICK and EFFECT_HEAVY_CLICK to the same HAL constant, which would be the Medium amplitude level HAL constant. If your device supports only one HAL constant with discrete amplitude, consider merging all three levels into one.

Continuous model

The continuous model with amplitude scalability can be applied to define HAL constants. A scale factor (S) can be applied to the HAL constants (for example, HAL_H0, HAL_H1) to produce the scaled HAL (HAL_H0 x S). In this case, the scaled HAL is mapped to define API constants (HAL_H0 x S1 = H0S1 = EFFECT_TICK) as shown in figure 16. By using amplitude scalability of the continuous model, a device can store a small number of HAL constants with distinctive textures and add amplitude variations by adjusting the scale factor (S). Device manufacturers can define the number of HAL constants based on how many different haptic textures they want to provide.

Figure 16. HAL constant range by texture (HAL_H0) and amplitude scale (S)

Figure 17. HAL-API constant mapping: Continuous model

In the continuous model, different HAL constants represent different haptic textures rather than different amplitudes; the scale factor (S) can configure the amplitude. However, because the perception of the texture (for example, sharpness) is related to the perception of the duration and amplitude, combining the texture and the scale factor (in the design process of HAL-API mapping) is recommended.

Figure 18 illustrates constant mapping by increasing variation from one HAL to many API constants with amplitude scalability.

Figure 18. Increasing variation with amplitude scalability

For all scalable API constants such as PRIMITIVE_TICK and PRIMITIVE_CLICK in VibrationEffect.Composition, the energy level of the API constant depends on the float scale parameter when the API constant is declared through addPrimitive(int primitiveID, float scale, int delay). PRIMITIVE_TICK and PRIMITIVE_CLICK can be designed with a clear distinction by using different HAL constants. This approach is recommended if you want to add variation to texture.