Struct tween::Tweener

pub struct Tweener<Value, Time, T: ?Sized> {
    pub current_time: Time,
    pub duration: Time,
    pub tween: T,
    /* private fields */
}

A Tweener is a wrapper around a Tween. Although you can tween dynamically using just a raw Tween, this struct will manage state and allow for more naturalistic handling.

When you create a Tweener, you’ll provide the start, end, and duration of the Tween (along with the actual tween itself). All of these are in absolute values. Internally, the Tweener, as with this library, works in “parametric” space, which is a fancy way of describing 0.0..=1.0, or a percentage of the Tween.

This struct has two important methods: move_to and move_by. move_to effectively just moves your time into parametric space (ie, takes a tween of length 4, and time 2, and gets the percent 0.5) and clamps the output to the start and end value in case you tried to move_to a time beyond the tween’s duration (a negative time, or a time > duration). move_by does the same, but given a relative value.

Clamping

A Tweener clamps its output value to within the range of start..=end given in new. This can easily happen moving a Tweener with move_by. To check if that’s occured, use is_finished, or, if negative movement is possible, invert is_valid.

For most users of this library, a common pattern will be:

let (start, end) = (0, 100);
let duration = 1;
let mut tweener = Tweener::linear(start, end, duration);

// and then in your main loop...
let dt = 1;
let mut last_value = None;
loop {
    last_value = Some(tweener.move_by(dt));
    // we'd want to run `!is_valid()` if negative movement was possible, but we know its not.
    if tweener.is_finished() {
        break;
    }
}
assert_eq!(last_value, Some(100));

What is finished and what is started exactly, though? In this library is_finished returns true when the Time is at or beyond the duration of the Tweener. This is a fancy way of saying if the Tweener has ran 5 frames, and its duration was 5, it will return true on is_finished.

We can demonstrate that here:

let (start, end) = (0, 2);
let duration = 2;
let mut tweener = Tweener::linear(start, end, duration);

let mut accum = 0;

loop {
    accum += dbg!(tweener.move_by(1));
    if tweener.is_finished() {
        break;
    }
}

assert_eq!(accum, 3);

NB: this is probably your assumption as to how this library works, but does mean that in a loop constructed like so, you will never actually see a clamp occur within move_by.

Finally, if you’d like this library to actually not clamp your tween, take a look at Extrapolator.

Iterator

In situations where the same delta time is alwayas used for move_by, you can instead convert a Tweener into a FixedTweener by into_fixed. See FixedTweener for more information.

Fields

current_time: Time

The current time of the Tweener. You can change this value at will without running the Tween, or change it with move_by.

duration: Time

The Tweener’s total duration.

tween: T

The actual underlying Tween.

Implementations

impl<Value, Time, T> Tweener<Value, Time, T>

where Time: TweenTime, Value: TweenValue, T: Tween<Value>,

pub fn new(start: Value, end: Value, duration: Time, tween: T) -> Self

Creates a new Tweener out of a Tween, start and end TweenValue, and TweenTime duration.

pub fn new_at( start: Value, end: Value, duration: Time, tween: T, current_time: Time ) -> Self

Creates a new Tweener out of a Tween, start and end TweenValue, TweenTime duration, and TweenTime current time.

Use this to have “negative” times in Tweeners. This can be useful for starting tweens “with a delay”. See the example in examples/delayed_tween.rs

pub fn map<R: Tween<Value>>( self, f: impl FnMut(T) -> R ) -> Tweener<Value, Time, R>

Maps a Tweener<Value, Time, T> to a Tweener<Value, Time, R>. This can be useful for boxing inner tweens.

pub fn move_to(&mut self, position: Time) -> Value

Moves the tween to a given Time. If this Tween previously was outside 0..=1 in parametric (percentage) space, ie. outside the duration of the tween or in negative time, this can move it back into bounds.

Giving TweenTime::ZERO to this function effectively resets a tweener.

Giving a negative time or a time beyond duration will move the tween there, but we will always clamp the output time.

pub fn move_by(&mut self, delta: Time) -> Value

Drives the Tweener forward X steps in time.

If an input higher than the tween’s duration is given, you will receive the max value of the tween.

pub fn initial_value(&self) -> Value

The initial value a tween was set to start at.

pub fn final_value(&self) -> Value

The final value the tween should end at.

pub fn is_started(&self) -> bool

Returns true is the Tweener’s current_time is greater than or equal to 0. Only negative times will return false.

Note that for tweens without bounds (infinite tweens like Looper), this method will always return true. Moreover, this method does not check if a tweener is finished. For that, use is_finished.

pub fn is_finished(&self) -> bool

Returns true is the Tweener’s current_time is greater than or equal to duration.

Note that for tweens without bounds (infinite tweens like Looper), this method will always return false. Moreover, this method does not check if a tweener is started. For that, use is_started.

pub fn is_valid(&self) -> bool

Returns true is the Tweener’s current_time is greater than or equal to 0 but less than duration.

Note that for tweens without bounds (infinite tweens like Looper), this method will always return true.

This method is rarely needed – only use it if you are doing some second-order tweening.

pub fn current_time_state(&self) -> CurrentTimeState

Returns CurrentTimeState based on the Tweener’s current_time.

Note that for tweens without bounds (in this library, Looper, Oscillator, and Extrapolator), this method will always return CurrentTimeState::Valid.

pub fn into_fixed(self, delta: Time) -> FixedTweener<Value, Time, T>

Converts this Tweener to a FixedTweener. See its documentation for more information.

impl<Value, Time> Tweener<Value, Time, Linear>

where Time: TweenTime, Value: TweenValue,

pub fn linear( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, Linear>

Creates a new Linear Tweener.

pub fn linear_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, Linear>

Creates a new Linear Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, CubicIn>

where Time: TweenTime, Value: TweenValue,

pub fn cubic_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, CubicIn>

Creates a new CubicIn Tweener.

pub fn cubic_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, CubicIn>

Creates a new CubicIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, CubicOut>

where Time: TweenTime, Value: TweenValue,

pub fn cubic_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, CubicOut>

Creates a new CubicOut Tweener.

pub fn cubic_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, CubicOut>

Creates a new CubicOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, CubicInOut>

where Time: TweenTime, Value: TweenValue,

pub fn cubic_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, CubicInOut>

Creates a new CubicInOut Tweener.

pub fn cubic_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, CubicInOut>

Creates a new CubicInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, SineIn>

where Time: TweenTime, Value: TweenValue,

pub fn sine_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, SineIn>

Creates a new SineIn Tweener.

pub fn sine_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, SineIn>

Creates a new SineIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, SineOut>

where Time: TweenTime, Value: TweenValue,

pub fn sine_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, SineOut>

Creates a new SineOut Tweener.

pub fn sine_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, SineOut>

Creates a new SineOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, SineInOut>

where Time: TweenTime, Value: TweenValue,

pub fn sine_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, SineInOut>

Creates a new SineOut Tweener.

pub fn sine_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, SineInOut>

Creates a new SineOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuintIn>

where Time: TweenTime, Value: TweenValue,

pub fn quint_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuintIn>

Creates a new QuintInOut Tweener.

pub fn quint_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuintIn>

Creates a new QuintInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuintOut>

where Time: TweenTime, Value: TweenValue,

pub fn quint_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuintOut>

Creates a new QuintOut Tweener.

pub fn quint_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuintOut>

Creates a new QuintOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuintInOut>

where Time: TweenTime, Value: TweenValue,

pub fn quint_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuintInOut>

Creates a new QuintInOut Tweener.

pub fn quint_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuintInOut>

Creates a new QuintInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuadIn>

where Time: TweenTime, Value: TweenValue,

pub fn quad_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuadIn>

Creates a new QuadIn Tweener.

pub fn quad_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuadIn>

Creates a new QuadIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuadOut>

where Time: TweenTime, Value: TweenValue,

pub fn quad_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuadOut>

Creates a new QuadOut Tweener.

pub fn quad_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuadOut>

Creates a new QuadOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuadInOut>

where Time: TweenTime, Value: TweenValue,

pub fn quad_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuadInOut>

Creates a new QuadInOut Tweener.

pub fn quad_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuadInOut>

Creates a new QuadInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuartIn>

where Time: TweenTime, Value: TweenValue,

pub fn quart_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuartIn>

Creates a new QuartIn Tweener.

pub fn quart_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuartIn>

Creates a new QuartIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuartOut>

where Time: TweenTime, Value: TweenValue,

pub fn quart_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuartOut>

Creates a new QuartOut Tweener.

pub fn quart_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuartOut>

Creates a new QuartOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, QuartInOut>

where Time: TweenTime, Value: TweenValue,

pub fn quart_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, QuartInOut>

Creates a new QuartInOut Tweener.

pub fn quart_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, QuartInOut>

Creates a new QuartInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, ExpoIn>

where Time: TweenTime, Value: TweenValue,

pub fn expo_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, ExpoIn>

Creates a new ExpoIn Tweener.

pub fn expo_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, ExpoIn>

Creates a new ExpoIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, ExpoOut>

where Time: TweenTime, Value: TweenValue,

pub fn expo_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, ExpoOut>

Creates a new ExpoOut Tweener.

pub fn expo_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, ExpoOut>

Creates a new ExpoOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, ExpoInOut>

where Time: TweenTime, Value: TweenValue,

pub fn expo_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, ExpoInOut>

Creates a new ExpoInOut Tweener.

pub fn expo_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, ExpoInOut>

Creates a new ExpoInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, CircIn>

where Time: TweenTime, Value: TweenValue,

pub fn circ_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, CircIn>

Creates a new CircIn Tweener.

pub fn circ_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, CircIn>

Creates a new CircIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, CircOut>

where Time: TweenTime, Value: TweenValue,

pub fn circ_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, CircOut>

Creates a new CircOut Tweener.

pub fn circ_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, CircOut>

Creates a new CircOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, CircInOut>

where Time: TweenTime, Value: TweenValue,

pub fn circ_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, CircInOut>

Creates a new CircInOut Tweener.

pub fn circ_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, CircInOut>

Creates a new CircInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, BackIn>

where Time: TweenTime, Value: TweenValue,

pub fn back_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, BackIn>

Creates a new BackIn Tweener.

pub fn back_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, BackIn>

Creates a new BackIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, BackOut>

where Time: TweenTime, Value: TweenValue,

pub fn back_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, BackOut>

Creates a new BackOut Tweener.

pub fn back_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, BackOut>

Creates a new BackOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, BackInOut>

where Time: TweenTime, Value: TweenValue,

pub fn back_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, BackInOut>

Creates a new BackInOut Tweener.

pub fn back_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, BackInOut>

Creates a new BackInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, ElasticIn>

where Time: TweenTime, Value: TweenValue,

pub fn elastic_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, ElasticIn>

Creates a new ElasticIn Tweener.

pub fn elastic_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, ElasticIn>

Creates a new ElasticIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, ElasticOut>

where Time: TweenTime, Value: TweenValue,

pub fn elastic_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, ElasticOut>

Creates a new ElasticOut Tweener.

pub fn elastic_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, ElasticOut>

Creates a new ElasticOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, ElasticInOut>

where Time: TweenTime, Value: TweenValue,

pub fn elastic_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, ElasticInOut>

Creates a new ElasticInOut Tweener.

pub fn elastic_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, ElasticInOut>

Creates a new ElasticInOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, BounceIn>

where Time: TweenTime, Value: TweenValue,

pub fn bounce_in( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, BounceIn>

Creates a new BounceIn Tweener.

pub fn bounce_in_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, BounceIn>

Creates a new BounceIn Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, BounceOut>

where Time: TweenTime, Value: TweenValue,

pub fn bounce_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, BounceOut>

Creates a new BounceOut Tweener.

pub fn bounce_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, BounceOut>

Creates a new BounceOut Tweener at the given time.

impl<Value, Time> Tweener<Value, Time, BounceInOut>

where Time: TweenTime, Value: TweenValue,

pub fn bounce_in_out( start: Value, end: Value, duration: Time ) -> Tweener<Value, Time, BounceInOut>

Creates a new BounceInOut Tweener.

pub fn bounce_in_out_at( start: Value, end: Value, duration: Time, current_time: Time ) -> Tweener<Value, Time, BounceInOut>

Creates a new BounceInOut Tweener at the given time.

Trait Implementations

impl<Value: Clone, Time: Clone, T: Clone + ?Sized> Clone for Tweener<Value, Time, T>

fn clone(&self) -> Tweener<Value, Time, T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Value: Debug, Time: Debug, T: Debug + ?Sized> Debug for Tweener<Value, Time, T>

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

Formats the value using the given formatter.

impl<Value: Ord, Time: Ord, T: Ord + ?Sized> Ord for Tweener<Value, Time, T>

fn cmp(&self, other: &Tweener<Value, Time, T>) -> Ordering

This method returns an Ordering between self and other.

impl<Value: PartialEq, Time: PartialEq, T: PartialEq + ?Sized> PartialEq for Tweener<Value, Time, T>

fn eq(&self, other: &Tweener<Value, Time, T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Value: PartialOrd, Time: PartialOrd, T: PartialOrd + ?Sized> PartialOrd for Tweener<Value, Time, T>

fn partial_cmp(&self, other: &Tweener<Value, Time, T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Value: Copy, Time: Copy, T: Copy + ?Sized> Copy for Tweener<Value, Time, T>

impl<Value: Eq, Time: Eq, T: Eq + ?Sized> Eq for Tweener<Value, Time, T>

impl<Value, Time, T: ?Sized> StructuralPartialEq for Tweener<Value, Time, T>