PhosphorAnimation::Spring Class Reference

Damped harmonic oscillator. More...

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

Inheritance diagram for PhosphorAnimation::Spring:

Public Member Functions
	Spring ()=default
	Spring (qreal omega, qreal zeta)
	Spring (const Spring &)=default
Spring &	operator= (const Spring &)=default
	Spring (Spring &&)=default
Spring &	operator= (Spring &&)=default
QString	typeId () const override
	Stable identifier for this curve subclass (e.g. "bezier", "spring").
qreal	evaluate (qreal t) const override
	Evaluate at normalized time t in [0,1]. May overshoot by design.
void	step (qreal dt, CurveState &state, qreal target) const override
	Advance state by dt real seconds toward target.
bool	isStateful () const override
	True if this curve requires persistent CurveState across frames.
qreal	settleTime () const override
	Approximate settle time in seconds.
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 for underdamped (zeta < 1). Critical/overdamped never overshoot.
bool	equals (const Curve &other) const override
	Same typeId + same parameters.
bool	operator== (const Spring &other) const
bool	operator!= (const Spring &other) const
Public Member Functions inherited from PhosphorAnimation::Curve
virtual	~Curve ()=default

Static Public Member Functions
static Spring	fromString (const QString &str)
	Parse from "spring:omega,zeta" or "omega,zeta". Clamps to valid ranges.
static Spring	snappy ()
	Responsive, slight overshoot.
static Spring	smooth ()
	Critically damped, no overshoot.
static Spring	bouncy ()
	Visible bounce.

Public Attributes
qreal	omega = 12.0
	Angular natural frequency (rad/s). [0.1, 200].
qreal	zeta = 0.8
	Damping ratio. [0.0, 10.0].

Static Public Attributes
static constexpr qreal	MaxSettleSeconds = 30.0
	Hard ceiling on settleTime(), in seconds.

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

Damped harmonic oscillator.

Params: omega (angular frequency, rad/s, [0.1,200]) and zeta (damping ratio, [0,10]). Matches Framer Motion / SwiftUI conventions. evaluate() = analytical step-response; step() = semi-implicit Euler integration. Wire format: "spring:omega,zeta".

Constructor & Destructor Documentation

Spring() [1/4]

PhosphorAnimation::Spring::Spring ( )

default

Spring() [2/4]

PhosphorAnimation::Spring::Spring	(	qreal	omega,
		qreal	zeta
	)

Spring() [3/4]

PhosphorAnimation::Spring::Spring ( const Spring &  )

default

Spring() [4/4]

PhosphorAnimation::Spring::Spring ( Spring &&  )

default

Member Function Documentation

bouncy()

static Spring PhosphorAnimation::Spring::bouncy ( )

static

Visible bounce.

clone()

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

overridevirtual

Deep copy with identical parameters.

Implements PhosphorAnimation::Curve.

equals()

bool PhosphorAnimation::Spring::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::Spring::evaluate ( qreal  t ) const

overridevirtual

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

Implements PhosphorAnimation::Curve.

fromString()

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

static

Parse from "spring:omega,zeta" or "omega,zeta". Clamps to valid ranges.

isStateful()

bool PhosphorAnimation::Spring::isStateful ( ) const

inlineoverridevirtual

True if this curve requires persistent CurveState across frames.

Reimplemented from PhosphorAnimation::Curve.

operator!=()

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

inline

operator=() [1/2]

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

default

operator=() [2/2]

Spring & PhosphorAnimation::Spring::operator= ( Spring &&  )

default

operator==()

bool PhosphorAnimation::Spring::operator==

(

const Spring &

other

)

const

overshoots()

bool PhosphorAnimation::Spring::overshoots ( ) const

overridevirtual

True for underdamped (zeta < 1). Critical/overdamped never overshoot.

Reimplemented from PhosphorAnimation::Curve.

settleTime()

qreal PhosphorAnimation::Spring::settleTime ( ) const

overridevirtual

Approximate settle time in seconds.

Parametric: 1.0 (the [0,1] domain). Spring: the analytical settling time — when the response first comes within SettleBand (0.5%) of the target — capped at Spring::MaxSettleSeconds. The band is deliberately tighter than the 2% control-theory convention, because this value IS an animation lifetime and the residual at it is a visible terminal jump.

MUST be finite and strictly positive. Callers use this as an animation LIFETIME — AnimatedValue::advance ends a stateful animation on it and ShaderInternal::resolveTransitionLifetimeMs arms a shader transition with it — so a zero or negative value would complete the animation instantly, and a non-finite one would never complete it.

Reimplemented from PhosphorAnimation::Curve.

smooth()

static Spring PhosphorAnimation::Spring::smooth ( )

static

Critically damped, no overshoot.

snappy()

static Spring PhosphorAnimation::Spring::snappy ( )

static

Responsive, slight overshoot.

step()

void PhosphorAnimation::Spring::step ( qreal  dt, CurveState &  state, qreal  target  ) const

overridevirtual

Advance state by dt real seconds toward target.

dt <= 0 is a no-op. Default impl maps to parametric evaluation using state.startValue/time/duration. For retarget with stateless curves: set startValue = value, time = 0 before changing target.

Reimplemented from PhosphorAnimation::Curve.

toString()

QString PhosphorAnimation::Spring::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::Spring::typeId ( ) const

overridevirtual

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

Implements PhosphorAnimation::Curve.

Member Data Documentation

MaxSettleSeconds

constexpr qreal PhosphorAnimation::Spring::MaxSettleSeconds = 30.0

staticconstexpr

Hard ceiling on settleTime(), in seconds.

A spring's analytical settle time diverges as zeta*omega approaches 0 (an undamped spring never settles at all), so it is capped here to keep repaint budgets and timer delays bounded for pathological parameters. Public because callers reason about the bound: the compositor's shader lifetime, the geometry animator's completion test, and AnimationLimits.h all reference it, and test_spring asserts against it.

omega

qreal PhosphorAnimation::Spring::omega = 12.0

Angular natural frequency (rad/s). [0.1, 200].

zeta

qreal PhosphorAnimation::Spring::zeta = 0.8

Damping ratio. [0.0, 10.0].

---

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

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