VibrationEffect.BasicEnvelopeBuilder Class

Definition

[Android.Runtime.Register("android/os/VibrationEffect$BasicEnvelopeBuilder", ApiSince=36, DoNotGenerateAcw=true)]
public sealed class VibrationEffect.BasicEnvelopeBuilder : Java.Lang.Object

[<Android.Runtime.Register("android/os/VibrationEffect$BasicEnvelopeBuilder", ApiSince=36, DoNotGenerateAcw=true)>]
type VibrationEffect.BasicEnvelopeBuilder = class
    inherit Object

Inheritance

Object

Object

VibrationEffect.BasicEnvelopeBuilder

Attributes

RegisterAttribute

Remarks

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.

<b>Intensity:</b> 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.

<b>Sharpness:</b> 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: <ul> <li>It may not use the full range of frequencies</li> <li>It's restricted to a frequency range that can generate output of at least 10 db SL</li> <li>Effects must end with a zero intensity control point. Failure to end at a zero intensity control point will result in an IllegalStateException.</li> </ul>

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();
            }

Java documentation for android.os.VibrationEffect.BasicEnvelopeBuilder.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.