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.

Parameters

Name	Description	Range	Setter	Getter	Flow
duration	Duration of the ramp transition.	> 0 (s)	duration(v)	duration()	Duration()
speed	Rate of change (change-per-second).	> 0	speed(v)	speed()	Speed()

Usage

There are two ways to start the ramp:

• go(from, to, duration): ramp will transition from value from to value to in duration seconds.

• go(to, duration): starts 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

Plotter serialOut(115200);

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 pq::Unit, public pq::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).

inline virtual float to() const

Returns destination value of the ramp,.

virtual void to(float to)

Assigns destination value of the ramp, starting from current value.

Parameters

to – the final value

inline virtual float from() const

Returns initial value of the ramp.

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

inline virtual float duration() const override

Returns the duration of the ramp (in seconds).

virtual void duration(float duration) override

Sets the duration of the ramp (in seconds).

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.

inline Parameter Speed()

Returns speed (rate of change) as a parameter.

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.

inline virtual Parameter Duration()

Returns duration as a parameter.

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

See Also

• Alarm

• Chronometer

• Easings

• Metronome

• Wave