BasicEnvelopeBuilder

Kotlin |Java

class BasicEnvelopeBuilder

kotlin.Any
↳	android.os.VibrationEffect.BasicEnvelopeBuilder

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:

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

Summary

Public constructors
`BasicEnvelopeBuilder()`

Public methods
VibrationEffect.BasicEnvelopeBuilder	`addControlPoint(intensity: Float, sharpness: Float, durationMillis: Long)` Adds a new control point to the end of this waveform envelope.
VibrationEffect	`build()` Build the waveform as a single `VibrationEffect`.
VibrationEffect.BasicEnvelopeBuilder	`setInitialSharpness(initialSharpness: Float)` Sets the initial sharpness for the basic envelope effect.

Public constructors

BasicEnvelopeBuilder

Added in API level Baklava

BasicEnvelopeBuilder()

Public methods

addControlPoint

Added in API level Baklava

fun addControlPoint(
    intensity: Float, 
    sharpness: Float, 
    durationMillis: Long
): VibrationEffect.BasicEnvelopeBuilder

Adds a new control point to the end of this waveform envelope.

Intensity defines the overall strength of the vibration, ranging from 0 (off) to 1 (maximum achievable strength). Higher values translate to stronger vibrations.

Sharpness defines the crispness of the vibration, ranging from 0 to 1. Lower values translate to smoother vibrations, while higher values create a sharper more snappy sensation. This value is mapped to the supported frequency range of the device.

Time specifies the duration (in milliseconds) for the vibrator to smoothly transition from the previous control point to this new one. It must be greater than zero. To transition as quickly as possible, use VibratorEnvelopeEffectInfo.getMinControlPointDurationMillis().

Parameters
`intensity`	Float: The target vibration intensity, ranging from 0 (off) to 1 (maximum strength). Value is between 0 and 1 inclusive
`sharpness`	Float: The target sharpness, ranging from 0 (smoothest) to 1 (sharpest). Value is between 0 and 1 inclusive
`durationMillis`	Long: The transition time in milliseconds. Value is a non-negative duration in milliseconds.

Return
`VibrationEffect.BasicEnvelopeBuilder`	This value cannot be `null`.

build

Added in API level Baklava

fun build(): VibrationEffect

Build the waveform as a single VibrationEffect.

The BasicEnvelopeBuilder object is still valid after this call, so you can continue adding more primitives to it and generating more VibrationEffects by calling this method again.

Return
`VibrationEffect`	The `VibrationEffect` resulting from the list of control points. This value cannot be `null`.

Exceptions
`java.lang.IllegalStateException`	if the last control point does not end at zero intensity.

setInitialSharpness

Added in API level Baklava

fun setInitialSharpness(initialSharpness: Float): VibrationEffect.BasicEnvelopeBuilder

Sets the initial sharpness for the basic envelope effect.

The effect will start vibrating at this sharpness when it transitions to the intensity and sharpness defined by the first control point.

The sharpness defines the crispness of the vibration, ranging from 0 to 1. Lower values translate to smoother vibrations, while higher values create a sharper more snappy sensation. This value is mapped to the supported frequency range of the device.

Parameters
`initialSharpness`	Float: The starting sharpness of the vibration in the range of [0, 1]. Value is between 0 and 1 inclusive

Return
`VibrationEffect.BasicEnvelopeBuilder`	This value cannot be `null`.