animation/spring.go
Functions
func Build
func (b *SpringBuilder) Build() *Spring {
s := b.spring
// Convert damping ratio to damping coefficient: d = 2 * zeta * sqrt(k * m)
if b.dampingSet {
s.damping = 2 * b.dampingRatio * float32(math.Sqrt(float64(s.stiffness*s.mass)))
}
return s
}
func Cancel
Cancel stops the spring immediately without calling OnDone.
func (s *Spring) Cancel() {
s.done = true
}
func DampingRatio
DampingRatio sets the damping ratio. Default is DampingNoBouncy (1.0).
Presets: DampingHighBouncy (0.2), DampingMediumBouncy (0.5),
DampingLowBouncy (0.75), DampingNoBouncy (1.0).
func (b *SpringBuilder) DampingRatio(ratio float32) *SpringBuilder {
b.dampingRatio = ratio
b.dampingSet = true
return b
}
func InitialVelocity
InitialVelocity sets the initial velocity. Default is 0.
func (b *SpringBuilder) InitialVelocity(v float32) *SpringBuilder {
b.spring.velocity = v
return b
}
func Mass
Mass sets the mass. Default is 1.0. Higher mass = slower response.
func (b *SpringBuilder) Mass(m float32) *SpringBuilder {
b.spring.mass = m
return b
}
func OnDone
OnDone sets a callback invoked when the spring settles.
func (b *SpringBuilder) OnDone(fn func()) *SpringBuilder {
b.spring.onDone = fn
return b
}
func RestDelta
RestDelta sets the position convergence threshold. Default is 0.5 (sub-pixel).
func (b *SpringBuilder) RestDelta(d float32) *SpringBuilder {
b.spring.restDelta = d
return b
}
func RestSpeed
RestSpeed sets the velocity convergence threshold. Default is 10.0 (px/s).
func (b *SpringBuilder) RestSpeed(s float32) *SpringBuilder {
b.spring.restSpeed = s
return b
}
func SpringTo
SpringTo creates a new SpringBuilder that animates the signal to the target.
The spring starts from the signal's current value with zero initial velocity.
If a previous spring on the same signal is canceled via auto-cancel,
velocity is automatically transferred.
func SpringTo(signal signalFloat32, target float32) *SpringBuilder {
return &SpringBuilder{
spring: &Spring{
signal: signal,
target: target,
mass: defaultMass,
stiffness: StiffnessMedium,
restDelta: defaultRestDelta,
restSpeed: defaultRestSpeed,
position: signal.Get(),
},
dampingRatio: DampingNoBouncy,
dampingSet: true,
}
}
func Start
Start builds the spring and registers it with the controller.
If another animation is running on the same signal, it is auto-canceled.
If the canceled animation was a Spring, its velocity is transferred.
func (b *SpringBuilder) Start(ctrl *Controller) *Spring {
s := b.Build()
ctrl.addSpring(s)
return s
}
func Stiffness
Stiffness sets the spring constant k. Default is StiffnessMedium (1500).
func (b *SpringBuilder) Stiffness(k float32) *SpringBuilder {
b.spring.stiffness = k
return b
}
func Velocity
Velocity returns the current velocity of the spring.
This is used for velocity preservation when re-targeting a spring.
func (s *Spring) Velocity() float32 {
return s.velocity
}
Structs
type Spring struct
Spring represents a running spring animation that drives a Signal[float32].
It uses the damped harmonic oscillator model:
F = -k*x - d*v
a = F / m
where k is stiffness, d is damping coefficient, m is mass, x is displacement
from target, and v is velocity.
Convergence is detected using the dual-threshold approach: the spring is
settled when both |position - target| < restDelta AND |velocity| < restSpeed.
type Spring struct {
signal signalFloat32
target float32
mass float32
stiffness float32
damping float32
// Convergence thresholds
restDelta float32
restSpeed float32
// State
position float32
velocity float32
done bool
onDone func()
}
type SpringBuilder struct
SpringBuilder constructs a Spring using the builder pattern.
Example:
animation.SpringTo(position, 200.0).
Stiffness(animation.StiffnessMedium).
DampingRatio(animation.DampingNoBouncy).
Start(ctrl)
type SpringBuilder struct {
spring *Spring
dampingRatio float32
dampingSet bool
}
Build returns the configured Spring without starting it.