Struct SpringConfig 

pub struct SpringConfig {
    pub stiffness: f32,
    pub damping: f32,
    pub mass: f32,
}

The physical parameters of a damped spring that moves a scalar toward a target.

Stiffness pulls the value toward its target, damping removes energy, and mass resists both. Keep one set of parameters for every step of an animation. stiffness and mass must be finite and positive; damping must be finite and non-negative. The constructor does not validate them, so invalid values can produce NaN or meaningless motion.

Create one with spring. Pass it to SpringAnimation::new to animate an element, or step it yourself with SpringConfig::step.

Examples

use gpui::spring;

let config = spring(100., 10., 1.);
let (natural_frequency, damping_ratio) = config.canonical();
assert_eq!(natural_frequency, 10.0);
assert_eq!(damping_ratio, 0.5);

See the animation guide for how spring state is retained between frames.

Fields

stiffness: f32

The spring constant, written $k$. A larger value pulls the spring toward its target more strongly.

damping: f32

The viscous damping coefficient, written $c$. With zero damping, a spring set in motion keeps oscillating instead of losing energy.

mass: f32

The moving mass, written $m$. A larger mass responds more slowly.

Implementations

impl SpringConfig

pub const fn new(stiffness: f32, damping: f32, mass: f32) -> Self

Creates a spring from its stiffness, damping and mass. See spring.

pub fn canonical(&self) -> (f32, f32)

Returns the natural angular frequency $\omega_0$ and the damping ratio $\zeta$.

A ratio below one describes an underdamped spring, which oscillates about its target. One is critical damping; above one is overdamping. For a displaced spring released from rest, critical damping gives the fastest approach to a fixed target without oscillation. A spring that already has velocity can cross the target even with critical damping.

pub fn step( &self, state: SpringState, target: f32, delta_time: f32, ) -> SpringState

Advances the spring by delta_time seconds toward a fixed target.

The solver assumes target stays fixed during delta_time and computes motion from elapsed time rather than a fixed frame duration. Splitting an interval into smaller steps gives the same motion apart from numerical error. Velocity carries over, so retargeting an interrupted spring does not restart it from rest.

Examples

use gpui::{SpringState, spring};

let config = spring(320., 24., 1.);
let start = SpringState::default();
let one_step = config.step(start, 1.0, 1.0 / 60.0);
let two_steps = config.step(config.step(start, 1.0, 1.0 / 120.0), 1.0, 1.0 / 120.0);
assert!((one_step.position - two_steps.position).abs() < 1e-3);
assert!(one_step.position > 0.0 && one_step.position < 1.0);

pub fn step_ramp( &self, state: SpringState, target: f32, target_velocity: f32, delta_time: f32, ) -> SpringState

Advances the spring by delta_time seconds toward a target that moves at target_velocity.

Use this for a target that moves steadily, such as a dragged pointer. With positive damping, the transient motion dies away and the spring approaches a constant lag behind the moving target. Using step would instead treat the target as fixed within each frame, introducing a lag that depends on frame duration.

Examples

use gpui::{SpringState, spring};

// A natural frequency of 10 and a damping ratio of 0.8.
let config = spring(100., 16., 1.);
let state = SpringState { position: -0.48, velocity: 3.0 };
let next = config.step_ramp(state, 0.0, 3.0, 0.25);
assert!((next.position - 0.27).abs() < 1e-4);
assert!((next.velocity - 3.0).abs() < 1e-4);

pub fn propagator(&self, delta_time: f32) -> [[f32; 2]; 2]

Returns the exact state-transition matrix for a fixed target over delta_time seconds.

The matrix maps the displacement from the target and the velocity to their values after delta_time, which is what step does. Build it once when many springs share this config and frame delta. Rebuild it when the delta changes.

Examples

use gpui::spring;

// With no time elapsed, nothing changes.
let matrix = spring(100., 10., 1.).propagator(0.0);
assert_eq!(matrix, [[1.0, 0.0], [0.0, 1.0]]);

pub fn is_settled(&self, state: SpringState, target: f32, epsilon: f32) -> bool

Returns whether the spring is within epsilon of target, in position and velocity.

The position must be within epsilon of target. The velocity must be at most epsilon * natural_frequency, which puts it on the same scale as position. A negative or non-finite epsilon never settles.

Examples

use gpui::{SpringState, spring};

let config = spring(100., 10., 1.);
let moving = SpringState { position: 1.0, velocity: 1.0 };
let nearly_still = SpringState { position: 1.005, velocity: 0.05 };
assert!(!config.is_settled(moving, 1.0, 0.01));
assert!(config.is_settled(nearly_still, 1.0, 0.01));

pub fn settle_time( &self, state: SpringState, target: f32, epsilon: f32, ) -> Duration

Returns a time after which the spring stays settled, measured from state in seconds.

The result is conservative. Stepping the spring to this time, or any later time, leaves it settled by is_settled with the same target and epsilon. An undamped spring that isn’t already at rest never settles, so this returns Duration::MAX. So does a non-positive or non-finite epsilon, unless the spring is already at rest.

Examples

use std::time::Duration;

use gpui::{SpringState, spring};

let config = spring(100., 10., 1.);
let start = SpringState::default();
let time = config.settle_time(start, 1.0, 0.001);
assert!(time > Duration::ZERO && time < Duration::MAX);
let later = config.step(start, 1.0, time.as_secs_f32() + 0.1);
assert!(config.is_settled(later, 1.0, 0.001));

assert_eq!(spring(100., 0., 1.).settle_time(start, 1.0, 0.001), Duration::MAX);

Trait Implementations

impl Clone for SpringConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SpringConfig

impl Debug for SpringConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<SpringConfig> for Motion<SpringDescription>

fn from(config: SpringConfig) -> Self

Converts to this type from the input type.

impl From<SpringConfig> for AnyMotion

fn from(config: SpringConfig) -> Self

Converts to this type from the input type.

impl PartialEq for SpringConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SpringConfig