Control.Varying.Tween

Tweening is a technique of generating intermediate samples of a type between a start and end value. By sampling a running tween each frame we get a smooth animation of a value over time.

At first release varying is only capable of tweening numerical values of type (Fractional t, Ord t) => t that match the type of time you use. At some point it would be great to be able to tween arbitrary types, and possibly tween one type into another (pipe dreams).

Tweening types

type Easing t f = t -> f -> t -> t

An easing function. The parameters are often named c, t and b, where c is the total change in value over the complete duration (endValue - startValue), t is the current percentage (0 to 1) of the duration that has elapsed and b is the start value.

To make things simple only numerical values can be tweened and the type of time deltas much match the tween's value type. This may change in the future :)

type TweenT f t m = SplineT f t (StateT f m)

type Tween f t = TweenT f t Identity

Running tweens

runTweenT :: (Monad m, Num f) => TweenT f t m x -> f -> f -> m (Either x (t, TweenT f t m x), f)

scanTween :: (Functor m, Applicative m, Monad m, Num f) => TweenT f t m a -> t -> [f] -> m [t]

tweenStream :: (Applicative m, Monad m, Num f) => TweenT f t m x -> t -> VarT m f t

Converts a tween into a continuous value stream. This is the tween version of outputStream.

Creating tweens

The most direct route toward tweening values is to use tween along with an interpolation function such as easeInExpo. For example, tween easeInExpo 0 100 10, this will create a spline that produces a number interpolated from 0 to 100 over 10 seconds. At the end of the tween the spline will return the result value.

tween :: (Applicative m, Monad m, Real f, Fractional f, Real t, Fractional t) => Easing t f -> t -> t -> f -> TweenT f t m t

Creates a spline that produces a value interpolated between a start and end value using an easing equation (Easing) over a duration. The resulting spline will take a time delta as input. For example:

testWhile_ isEvent (deltaUTC >>> v)
   where v :: VarT IO a (Event Double)
         v = flip outputStream 0 $ tween easeOutExpo 0 100 5

Keep in mind tween must be fed time deltas, not absolute time or duration. This is mentioned because the author has made that mistake more than once ;)

tween concludes returning the latest output value.

tween_ :: (Applicative m, Monad m, Real t, Fractional t, Real f, Fractional f) => Easing t f -> t -> t -> f -> TweenT f t m ()

A version of tween that discards the result. It is simply

tween f a b c >> return ()

constant :: (Applicative m, Monad m, Num t, Ord t) => a -> t -> TweenT t a m a

Creates a tween that performs no interpolation over the duration.

withTween :: (Applicative m, Monad m, Real t, Fractional t, Real a, Fractional a) => Easing t a -> t -> t -> a -> (t -> x) -> TweenT a x m t

A version of tween that maps its output using the given constant function. withTween ease from to dur f = mapOutput (pure f) $ tween ease from to dur

withTween_ :: (Applicative m, Monad m, Real t, Fractional t, Real a, Fractional a) => Easing t a -> t -> t -> a -> (t -> x) -> TweenT a x m ()

A version of withTween that discards its output.

Interpolation functions

These pure functions take a c (total change in value, ie end - start), t (percent of duration completion) and b (start value) and result in and interpolation of a value. To see what these look like please check out http://www.gizma.com/easing/.

linear :: (Floating t, Real f) => Easing t f

Ease linear.

easeInCirc :: (Floating t, Real f, Floating f) => Easing t f

Ease in circular.

easeOutCirc :: (Floating t, Real f) => Easing t f

Ease out circular.

easeInExpo :: (Floating t, Real f) => Easing t f

Ease in exponential.

easeOutExpo :: (Floating t, Real f) => Easing t f

Ease out exponential.

easeInSine :: (Floating t, Real f) => Easing t f

Ease in sinusoidal.

easeOutSine :: (Floating t, Real f) => Easing t f

Ease out sinusoidal.

easeInOutSine :: (Floating t, Real f) => Easing t f

Ease in and out sinusoidal.

easeInPow :: (Num t, Fractional t, Real f) => Int -> Easing t f

Ease in by some power.

easeOutPow :: (Num t, Fractional t, Real f) => Int -> Easing t f

Ease out by some power.

easeInCubic :: (Num t, Fractional t, Real f) => Easing t f

Ease in cubic.

easeOutCubic :: (Num t, Fractional t, Real f) => Easing t f

Ease out cubic.

easeInQuad :: (Num t, Fractional t, Real f) => Easing t f

Ease in quadratic.

easeOutQuad :: (Num t, Fractional t, Real f) => Easing t f

Ease out quadratic.

Writing your own tweens

To create your own tweens just write a function that takes a start value, end value and a duration and return an event stream.

tweenInOutExpo start end dur = do
    (dt, x) <- tween easeInExpo start end (dur/2)
    tween easeOutExpo x end $ dt + dur/2