Ramp

A source unit that generates a smooth transition between two values. The unit can be triggered to start transitioning to a target value for a certain duration.

There are two ways to start the ramp.

By calling go(from, to, duration) the ramp will transition from value from to value to in duration seconds.

Alternatively, calling go(to, duration) will start a transition from the ramp’s current value to to in duration seconds.

The following diagram shows what happens to the ramp signal if go(5.0, 1.0, 2.0) is called, followed later by go(3.0, 1.0):

Important

Ramps also support the use of easing functions in order to create different kinds of expressive effects with signals. An easing function can optionally be specified at the end of a go() command or by calling the easing() function.

Please refer to this page for a full list of available easing functions.

Example

Sequentially ramps through different values.

#include <Plaquette.h>

Ramp myRamp(3.0); // initial duration: 3 seconds

StreamOut serialOut(Serial);

void begin() {
  // Apply an easing function (optional).
  myRamp.easing(easeOutSine);
  // Launch ramp: ramp from -10 to 10.
  myRamp.go(-10, 10);
}

void step() {
  if (myRamp.isFinished())
  {
    // Launch ramp from current value to half, increasing duration by one second.
    myRamp.go(myRamp / 2, myRamp.duration() + 1);
  }

  myRamp >> serialOut;
}

Reference

class Ramp : public Unit, public AbstractTimer

Provides a ramping / tweening mechanism that allows smooth transitions between two values.

Public Functions

Ramp(Engine &engine = Engine::primary())

Constructor.

Parameters: engine – the engine running this unit

Ramp(float duration, Engine &engine = Engine::primary())

Constructor with duration.

Parameters

duration – duration of the ramp
engine – the engine running this unit

virtual float get(): Returns value of ramp.

virtual float put(float value)

Forces value in the ramp.

If this happens while the ramp is running, it will interrupt the ramp.

Parameters: value – the value sent to the unit
Returns: the new value of the unit

virtual float mapTo(float toLow, float toHigh): Maps value to new range.

void easing(easing_function easing)

Sets easing function to apply to ramp.

Parameters: easing – the easing function

inline void noEasing(): Remove easing function (linear/no easing).

virtual void to(float to)

Assign final value of the ramp starting from current value.

Parameters: to – the final value

virtual void from(float from)

Assign initial value of the ramp.

Parameters: from – the initial value

virtual void fromTo(float from, float to)

Assign initial and final values of the ramp.

Parameters

from – the initial value
to – the final value

virtual void duration(float duration): Sets the duration of the chronometer.

inline virtual float duration() const: Returns duration.

virtual void speed(float speed): Sets the speed (rate of change) of the ramp in change-per-second.

virtual float speed() const: Returns speed (rate of change) of the ramp in change-per-second.

virtual void start(): Starts/restarts the ramp. Will repeat the last ramp.

virtual void go(float from, float to, float durationOrSpeed, easing_function easing = 0)

Starts a new ramp.

Parameters

from – the initial value
to – the final value
durationOrSpeed – the duration of the ramp (in seconds) or speed (in change-per-second) depending on mode
easing – the easing function (optional).

virtual void go(float to, float durationOrSpeed, easing_function easing = 0)

Starts a new ramp, starting from current value.

Parameters

to – the final value
durationOrSpeed – the duration of the ramp (in seconds) or speed (in change-per-second) depending on mode
easing – the easing function (optional)

virtual void go(float to, easing_function easing = 0)

Starts a new ramp, starting from current value (keeping the same duration/speed).

Parameters

to – the final value
easing – the easing function (optional)

virtual void mode(uint8_t mode): Changes the mode of the component (RAMP_DURATION or RAMP_SPEED).

inline uint8_t mode() const: Returns the mode of the component (RAMP_DURATION or RAMP_SPEED).

inline virtual bool finished(): Returns true iff the ramp just finished its process this step.

inline virtual void onFinish(EventCallback callback): Registers event callback on finish event.

virtual void setTime(float time): Forces current time (in seconds).

float durationToSpeed(float duration) const: Returns speed based on duration.

float speedToDuration(float speed) const: Returns duration based on speed.

virtual void start(float to, float durationOrSpeed, easing_function easing = 0)

Deprecated:

virtual void start(float from, float to, float durationOrSpeed, easing_function easing = 0)

Deprecated:

inline float seconds() const: Returns engine time in seconds.

inline uint32_t milliSeconds() const: Returns engine time in milliseconds.

inline uint64_t microSeconds() const: Returns engine time in microseconds.

inline unsigned long nSteps() const: Returns number of engine steps.

inline float sampleRate() const: Returns engine sample rate.

inline float samplePeriod() const: Returns enginesample period.

inline operator float(): Object can be used directly to access its value.

inline explicit operator bool(): Operator that allows usage in conditional expressions.

virtual void start(float duration): Starts/restarts the chronometer with specific duration.

virtual float progress() const: The progress of the timer process (in %).

inline virtual bool isFinished() const: Returns true iff the chronometer has finished its process.

inline virtual bool isComplete() const

Deprecated:

virtual void pause(): Interrupts the chronometer.

virtual void resume(): Resumes process.

inline virtual float elapsed() const: The time currently elapsed by the chronometer (in seconds).

virtual bool hasPassed(float timeout) const: Returns true iff elapsed time has passed given timeout.

virtual bool hasPassed(float timeout, bool restartIfPassed)

Deprecated:: Returns true iff elapsed time has passed given timeout (optional argument to automatically restart if true).

virtual void addTime(float time): Adds/subtracts time to the chronometer.

inline virtual bool isRunning() const: Returns true iff the chronometer is currently running.

inline bool isStarted() const

Deprecated:

virtual void stop(): Interrupts the chronometer and resets to zero.

virtual void togglePause(): Toggles pause/unpause.

Public Static Functions

static inline bool analogToDigital(float f): Converts analog (float) value to digital (bool) value.

static inline float digitalToAnalog(bool b): Converts digital (bool) value to analog (float) value.

Ramp

Example

Reference

See Also