VibrationEffect.BasicEnvelopeBuilder

public static final class VibrationEffect.BasicEnvelopeBuilder
extends Object

A builder for waveform effects defined by their envelope, designed to provide a consistent haptic perception across devices with varying capabilities.

This builder simplifies the creation of waveform effects by automatically adapting them to different devices based on their capabilities. Effects are defined by control points specifying target vibration intensity and sharpness, along with durations to reach those targets. The vibrator will smoothly transition between these control points.

Intensity: Defines the overall strength of the vibration, ranging from 0 (off) to 1 (maximum achievable strength). Higher values result in stronger vibrations. Supported intensity values guarantee sensitivity levels (SL) above 10 dB SL to ensure human perception.

Sharpness: Defines the crispness of the vibration, ranging from 0 to 1. Lower values produce smoother vibrations, while higher values create a sharper, more snappy sensation. Sharpness is mapped to its equivalent frequency within the device's supported frequency range.

While this builder handles most of the adaptation logic, it does come with some limitations:

• It may not use the full range of frequencies
• It's restricted to a frequency range that can generate output of at least 10 db SL
• Effects must end with a zero intensity control point. Failure to end at a zero intensity control point will result in an IllegalStateException.

The builder automatically starts all effects at 0 intensity.

To avoid these limitations and to have more control over the effects output, use WaveformEnvelopeBuilder, where direct amplitude and frequency values can be used.

For optimal cross-device consistency, it's recommended to limit the number of control points to a maximum of 16. However this is not mandatory, and if a pattern exceeds the maximum number of allowed control points, the framework will automatically break down the effect to ensure it plays correctly.

For example, the following code creates a vibration effect that ramps up the intensity from a low-pitched to a high-pitched strong vibration over 500ms and then ramps it down to 0 (off) over 100ms:

VibrationEffect effect = new VibrationEffect.BasicEnvelopeBuilder()
     .setInitialSharpness(0.0f)
     .addControlPoint(1.0f, 1.0f, 500)
     .addControlPoint(0.0f, 1.0f, 100)
     .build();
 

Summary

Public constructors

public BasicEnvelopeBuilder ()

Public methods

public VibrationEffect.BasicEnvelopeBuilder addControlPoint (float intensity, 
                float sharpness, 
                long durationMillis)

public VibrationEffect build ()

public VibrationEffect.BasicEnvelopeBuilder setInitialSharpness (float initialSharpness)