Summary: Ctors | Methods | Inherited Methods

VibrationEffect.WaveformEnvelopeBuilder

Kotlin |Java

public static final class VibrationEffect.WaveformEnvelopeBuilder
extends Object

java.lang.Object
↳	android.os.VibrationEffect.WaveformEnvelopeBuilder

A builder for waveform effects described by its envelope.

Waveform effect envelopes are defined by one or more control points describing a target vibration amplitude and frequency, and a duration to reach those targets. The vibrator will perform smooth transitions between control points.

For example, the following code ramps a vibrator from off to full amplitude at 120Hz over 100ms, holds that state for 200ms, and then ramps back down over 100ms:

VibrationEffect effect = new VibrationEffect.WaveformEnvelopeBuilder()
     .addControlPoint(1.0f, 120f, 100)
     .addControlPoint(1.0f, 120f, 200)
     .addControlPoint(0.0f, 120f, 100)
     .build();

The builder automatically starts all effects at 0 amplitude.

It is crucial to ensure that the frequency range used in your effect is compatible with the device's capabilities. The framework will not play any frequencies that fall partially or completely outside the device's supported range. It will also not attempt to correct or modify these frequencies.

Therefore, it is strongly recommended that you design your haptic effects with the device's frequency profile in mind. You can obtain the supported frequency range and other relevant frequency-related information by getting the VibratorFrequencyProfile using the Vibrator.getFrequencyProfile() method.

In addition to these limitations, when designing vibration patterns, it is important to consider the physical limitations of the vibration actuator. These limitations include factors such as the maximum number of control points allowed in an envelope effect, the minimum and maximum durations permitted for each control point, and the maximum overall duration of the effect. If a pattern exceeds the maximum number of allowed control points, the framework will automatically break down the effect to ensure it plays correctly.

You can use the following APIs to obtain these limits:

Maximum envelope control points: VibratorEnvelopeEffectInfo.getMaxSize()
Minimum control point duration: VibratorEnvelopeEffectInfo.getMinControlPointDurationMillis()
Maximum control point duration: VibratorEnvelopeEffectInfo.getMaxControlPointDurationMillis()
Maximum total effect duration: VibratorEnvelopeEffectInfo.getMaxDurationMillis()

Summary

Public constructors
`WaveformEnvelopeBuilder()`

Public methods
`VibrationEffect.WaveformEnvelopeBuilder`	`addControlPoint(float amplitude, float frequencyHz, long durationMillis)` Adds a new control point to the end of this waveform envelope.
`VibrationEffect`	`build()` Build the waveform as a single `VibrationEffect`.
`VibrationEffect.WaveformEnvelopeBuilder`	`setInitialFrequencyHz(float initialFrequencyHz)` Sets the initial frequency for the waveform in Hertz.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

WaveformEnvelopeBuilder

Added in Android Baklava

public WaveformEnvelopeBuilder ()

Public methods

addControlPoint

Added in Android Baklava

public VibrationEffect.WaveformEnvelopeBuilder addControlPoint (float amplitude, 
                float frequencyHz, 
                long durationMillis)

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

Amplitude defines the vibrator's strength at this frequency, ranging from 0 (off) to 1 (maximum achievable strength). This value scales linearly with output strength, not perceived intensity. It's determined by the actuator response curve.

Frequency must be greater than zero and within the supported range. To determine the supported range, use Vibrator.getFrequencyProfile(). Creating effects using frequencies outside this range will result in the vibration not playing.

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
`amplitude`	`float`: The amplitude value between 0 and 1, inclusive. 0 represents the vibrator being off, and 1 represents the maximum achievable amplitude at this frequency. Value is between 0 and 1 inclusive
`frequencyHz`	`float`: The frequency in Hz, must be greater than zero. Value is 0 or greater
`durationMillis`	`long`: The transition time in milliseconds. Value is a non-negative duration in milliseconds.

Returns
`VibrationEffect.WaveformEnvelopeBuilder`	This value cannot be `null`.

build

Added in Android Baklava

public VibrationEffect build ()

Build the waveform as a single VibrationEffect.

The WaveformEnvelopeBuilder 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.

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

Throws
`IllegalStateException`	if no control points were added to the builder.

setInitialFrequencyHz

Added in Android Baklava

public VibrationEffect.WaveformEnvelopeBuilder setInitialFrequencyHz (float initialFrequencyHz)

Sets the initial frequency for the waveform in Hertz.

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

The frequency must be greater than zero and within the supported range. To determine the supported range, use Vibrator.getFrequencyProfile(). Creating effects using frequencies outside this range will result in the vibration not playing.

Parameters
`initialFrequencyHz`	`float`: The starting frequency of the vibration, in Hz. Must be greater than zero. Value is 0 or greater

Returns
`VibrationEffect.WaveformEnvelopeBuilder`	This value cannot be `null`.