PhosphorAnimation::Easing Class Reference

Parametric easing curve: cubic bezier, elastic, or bounce. More...

#include <phosphor-animation/include/PhosphorAnimation/Easing.h>

Inheritance diagram for PhosphorAnimation::Easing:

Public Types
enum class	Type {   CubicBezier , ElasticIn , ElasticOut , ElasticInOut ,   BounceIn , BounceOut , BounceInOut }

Public Member Functions
	Easing ()=default
	Easing (const Easing &)=default
Easing &	operator= (const Easing &)=default
	Easing (Easing &&)=default
Easing &	operator= (Easing &&)=default
QString	typeId () const override
	Stable identifier for this curve subclass (e.g. "bezier", "spring").
qreal	evaluate (qreal x) const override
	Evaluate at normalized time t in [0,1]. May overshoot by design.
QString	toString () const override
	Serialize to "typeId:params" or bare "x1,y1,x2,y2" for cubic-bezier.
std::unique_ptr< Curve >	clone () const override
	Deep copy with identical parameters.
bool	overshoots () const override
	True if this curve may evaluate outside [0,1] during progression.
bool	equals (const Curve &other) const override
	Same typeId + same parameters.
bool	operator== (const Easing &other) const
bool	operator!= (const Easing &other) const
Public Member Functions inherited from PhosphorAnimation::Curve
virtual	~Curve ()=default
virtual void	step (qreal dt, CurveState &state, qreal target) const
	Advance state by dt real seconds toward target.
virtual bool	isStateful () const
	True if this curve requires persistent CurveState across frames.
virtual qreal	settleTime () const
	Approximate settle time in seconds.

Static Public Member Functions
static Easing	fromString (const QString &str)
	Parse from config string. Returns default OutCubic on failure.
static qreal	minElasticPeak (qreal period)
	The gentlest bounce elastic can make at period — the low end of the overshoot range, and it MOVES with the period.
static qreal	clampAmplitude (Type t, qreal amp, qreal period)
	Clamp amp to the range the given curve type actually honours.

Public Attributes
Type	type = Type::CubicBezier
qreal	x1 = 0.33
	Bezier control points (P1, P2). x clamped [0,1]; y clamped [-1,2].
qreal	y1 = 1.0
qreal	x2 = 0.68
qreal	y2 = 1.0
qreal	amplitude = 1.0
	Elastic: the PEAK VALUE the curve reaches, so 1.5 means it travels 50% past its target before settling back.
qreal	period = 0.3
	Elastic oscillation period: how FAST it wiggles.
int	bounces = 3
	Bounce count. [1, 8].

Static Public Attributes
static constexpr qreal	MaxElasticPeak = 2.0
	Highest peak an elastic curve may reach.
static constexpr qreal	MinElasticPeriod = 0.1
static constexpr qreal	MaxElasticPeriod = 1.0
static constexpr int	ElasticSolveIterations = 24
	Bisection steps used to invert the peak into an internal gain.

Additional Inherited Members
Protected Member Functions inherited from PhosphorAnimation::Curve
	Curve ()=default
	Curve (const Curve &)=default
Curve &	operator= (const Curve &)=default
	Curve (Curve &&)=default
Curve &	operator= (Curve &&)=default

Detailed Description

Parametric easing curve: cubic bezier, elastic, or bounce.

All stateless. Default construction yields OutCubic bezier (0.33, 1.00, 0.68, 1.00). Value type with public fields — can be stack-allocated or stored inline.

Member Enumeration Documentation

Type

enum class PhosphorAnimation::Easing::Type

strong

Enumerator
CubicBezier
ElasticIn
ElasticOut
ElasticInOut
BounceIn
BounceOut
BounceInOut

Constructor & Destructor Documentation

Easing() [1/3]

PhosphorAnimation::Easing::Easing ( )

default

Easing() [2/3]

PhosphorAnimation::Easing::Easing ( const Easing &  )

default

Easing() [3/3]

PhosphorAnimation::Easing::Easing ( Easing &&  )

default

Member Function Documentation

clampAmplitude()

static qreal PhosphorAnimation::Easing::clampAmplitude ( Type  t, qreal  amp, qreal  period  )

static

Clamp amp to the range the given curve type actually honours.

The two families share the amplitude field but not its meaning, so they do not share its bounds:

• Elastic's amplitude is the PEAK the curve reaches, so its range is the curve's own reachable one: [minElasticPeak(period), MaxElasticPeak]. It depends on the period, which is why this takes one.
• Bounce never leaves [0, 1] at any amplitude (see overshoots()), so the envelope has no claim on it and it keeps the wider [0.5, 3.0] range, where the value scales dip depth and every part of it is live. The period is ignored.

clone()

std::unique_ptr< Curve > PhosphorAnimation::Easing::clone ( ) const

overridevirtual

Deep copy with identical parameters.

Implements PhosphorAnimation::Curve.

equals()

bool PhosphorAnimation::Easing::equals ( const Curve &  other ) const

overridevirtual

Same typeId + same parameters.

Default compares toString() (2-decimal rounded); subclasses with precise floats should override.

Reimplemented from PhosphorAnimation::Curve.

evaluate()

qreal PhosphorAnimation::Easing::evaluate ( qreal  t ) const

overridevirtual

Evaluate at normalized time t in [0,1]. May overshoot by design.

Implements PhosphorAnimation::Curve.

fromString()

static Easing PhosphorAnimation::Easing::fromString ( const QString &  str )

static

Parse from config string. Returns default OutCubic on failure.

minElasticPeak()

static qreal PhosphorAnimation::Easing::minElasticPeak ( qreal  period )

static

The gentlest bounce elastic can make at period — the low end of the overshoot range, and it MOVES with the period.

The curve is pinned to 0 at t = 0, a full unit below the target, so its wave cannot start with a magnitude below 1. At a short period the crest arrives before the envelope has decayed, so that unavoidable magnitude still shows up as a big first bounce: about 1.71 at period 0.1, versus 1.05 at period 1.0. Callers surface this as the slider's minimum instead of clamping into it silently, because a range that lies about what it can reach is how the old amplitude parameter went wrong in the first place.

operator!=()

bool PhosphorAnimation::Easing::operator!= ( const Easing &  other ) const

inline

operator=() [1/2]

Easing & PhosphorAnimation::Easing::operator= ( const Easing &  )

default

operator=() [2/2]

Easing & PhosphorAnimation::Easing::operator= ( Easing &&  )

default

operator==()

bool PhosphorAnimation::Easing::operator==

(

const Easing &

other

)

const

overshoots()

bool PhosphorAnimation::Easing::overshoots ( ) const

overridevirtual

True if this curve may evaluate outside [0,1] during progression.

Reimplemented from PhosphorAnimation::Curve.

toString()

QString PhosphorAnimation::Easing::toString ( ) const

overridevirtual

Serialize to "typeId:params" or bare "x1,y1,x2,y2" for cubic-bezier.

2-decimal float precision — round-trip is lossy.

Implements PhosphorAnimation::Curve.

typeId()

QString PhosphorAnimation::Easing::typeId ( ) const

overridevirtual

Stable identifier for this curve subclass (e.g. "bezier", "spring").

Implements PhosphorAnimation::Curve.

Member Data Documentation

amplitude

qreal PhosphorAnimation::Easing::amplitude = 1.0

Elastic: the PEAK VALUE the curve reaches, so 1.5 means it travels 50% past its target before settling back.

Range [minElasticPeak(period), 2.0].

This is deliberately not the classic Penner amplitude, which is the wave's magnitude at t = 0 — a quantity the curve never actually displays, because it is pinned to 0 there. Under that parameterisation the overshoot you SAW was the amplitude decayed by however long the crest took to arrive, so it moved with the period: one amplitude spanned a 5x range of real overshoot depending on where the period slider sat. The parameter now means the thing the user is actually choosing, and the internal Penner gain is solved for (solveElasticGain).

Bounce: height scale, [0.5, 3.0] — unrelated meaning, see clampAmplitude.

bounces

int PhosphorAnimation::Easing::bounces = 3

Bounce count. [1, 8].

ElasticSolveIterations

constexpr int PhosphorAnimation::Easing::ElasticSolveIterations = 24

staticconstexpr

Bisection steps used to invert the peak into an internal gain.

24 steps over the [1, 16] bracket resolve the gain to ~1e-6, far below anything a pixel can show.

MaxElasticPeak

constexpr qreal PhosphorAnimation::Easing::MaxElasticPeak = 2.0

staticconstexpr

Highest peak an elastic curve may reach.

It is Limits::MaxCurveProgress, and the equality is the point: because amplitude IS the peak, capping it here makes the overshoot envelope EXACT for elastic rather than a bound the curve gets clipped against. Elastic-out tops out at exactly 2.0 and elastic-in, its mirror, bottoms out at exactly -1.0, so the two of them span the envelope precisely and nothing is ever clipped.

MaxElasticPeriod

constexpr qreal PhosphorAnimation::Easing::MaxElasticPeriod = 1.0

staticconstexpr

MinElasticPeriod

constexpr qreal PhosphorAnimation::Easing::MinElasticPeriod = 0.1

staticconstexpr

period

qreal PhosphorAnimation::Easing::period = 0.3

Elastic oscillation period: how FAST it wiggles.

It no longer sets how far the curve overshoots — amplitude does that on its own. [0.1, 1.0].

type

Type PhosphorAnimation::Easing::type = Type::CubicBezier

x1

qreal PhosphorAnimation::Easing::x1 = 0.33

Bezier control points (P1, P2). x clamped [0,1]; y clamped [-1,2].

x2

qreal PhosphorAnimation::Easing::x2 = 0.68

y1

qreal PhosphorAnimation::Easing::y1 = 1.0

y2

qreal PhosphorAnimation::Easing::y2 = 1.0

---

The documentation for this class was generated from the following file:

• phosphor-animation/include/PhosphorAnimation/Easing.h