gween

README

Gween

Gween (go-between) is a small library to perform tweening in Go. It has a minimal interface, and it comes with several easing functions.

Examples

package gween

import (
  "github.com/tanema/gween/ease"
  "github.com/tanema/gween/gween"
)

// increase the value from 0 to 5 in 10 seconds
var tweenLinear = gween.New(0, 5, 10, ease.Linear)
current, isFinished := tweenLinear.Update(dt)

// make some text fall from the top of the screen, bouncing on y=300, in 4 seconds
var tweenLabel = gween.new(0, 300, 4, ease.OutBounce)
label.Y, _ = tweenLabel.Update(dt)

// fade background from white to black and foregrond from black to red in 2 seconds
currentBGColor = [4]float32{255, 255, 255, 255}
currentColor = [4]float32{0, 0, 0, 0}
var tweenBackground = gween.new(255, 0, 2, ease.Linear)
var tweenRed = gween.new(255, 0, 2, ease.Linear)
currentBG, _ := tweenBackground.Update(dt)
currentBGColor = [4]float32{currentBG, currentBG, currentBG, currentBG}
currentColor[0], _ = tweenRed.Update(dt)

// sequence increasing linearly from 0 to 4 over 10 seconds, 
// then decreasing outElastic 4 to 0 over 2 seconds
var sequence = gween.NewSequence(
  gween.New(0, 4, 10, ease.Linear),
  gween.New(4, 0, 2, ease.OutElastic),
)
// set to infinitely loop
sequence.SetLoop(-1)
val, tweenCompleted, seqenceCompleted = sequence.Update(dt)

Interface

Tween

Creation

t := gween.New(begin, end, duration, easingFunction)

Creates a new tween.

• begin is the start value
• end is the ending value
• duration means how much the change will take until it's finished. It must be a positive number.
• easingFunction can be either a function or a function name (see the easing section below).

This function only creates and returns the tween. It must be captured in a variable and updated via t.Update(dt) in order for the changes to take place.

Methods

currentValue, isFinished := t.Update(dt)

Gradually changes the currentValue toward the end value as time passes.

• t is a tween returned by gween.New
• dt is the difference in time. It will be added to the internal time counter of the tween. The current value at the current value will be returned using selected easing function.
• currentValue is the current eased value for the current time.
• isFinised is true if the tween has reached its limit (its internal clock is >= duration). It is false otherwise.

When the tween is complete, the currentValue will be equal to the end value. The way they change over time will depend on the chosen easing function.

If dt is positive, the easing will be applied until the internal clock equals duration, at which point the easing will stop. If it is negative, the easing will play "backwards", until it reaches the initial value.

currentValue, isFinished := t.Set(clock)

Moves a tween's internal clock to a particular moment.

• t is a tween returned by gween.New
• clock is a positive number or 0. It's the new value of the tween's internal clock.
• currentValue is the value of the tween at the time set.
• isFinished works like in t.Update; it's true if the tween has reached its end, and false otherwise.

Sequence

Creation

s := gween.NewSeqence(tweens ...*Tween)

Sequences can be used to execute tweens in sequence. They also provide looping and "yoyo" functionality.

• tweens the tweens to be executed in sequential order

This function only creates and returns the sequence. It must be captured in a variable and updated via s.Update(dt) in order for the changes to take place.

Methods

currentValue, tweenCompleted, seqeuenceCompleted := s.Update(dt)

Gradually changes the currentValue from the begin value to the end value of each tween in the sequence as time passes. If a dt is too large for the current tween, the "overflow" amount will automatically be carried into the next tween until the entire dt is exhausted by the tweens in the sequence, or the sequence completes.

• s is a sequence returned by gween.NewSequence
• dt is the difference in time. It will be added to the internal time counter of the current tween and "overflow" to the next until completed exhausted.
• currentValue is the current eased value for the current time.
• tweenCompleted is true if any tween within the sequence has completed during this update.
• sequenceCompleted is true if the entire sequence and all loops have completed.
  • When configured to loop indefinitely, this will always be false

s.SetLoop(l)

Defaults to 1

Configures the sequence to "loop" l times. When l is -1, sequence will loop infinitely.

When used with s.SetYoyo(true), a single "loop" starts and ends at the beginning of the first tween; making its way out to the end of the final tween and back again.

s.SetYoyo(bool)

Defaults to false

Configures the sequence on whether to "yoyo" between the beginning of the first tween and the end of the last tween.

• When yoyo is false:
  • A single loop of the sequence is when all tweens are completed in forward order.
  • When the final loop of the sequence is complete, the currentValue will be equal to the end value of the final tween.
• When yoyo is true:
  • A single loop is when all tweens have completed in forward order, and then completed again in reverse order.
  • When the final loop of the sequence is complete, the currentValue will be equal to the begin value of the first tween.

s.Reset()

Resets all tweens in the sequence and sets the "current" tween back to the first. Also, sets the remaining loop count back to the initial value last set using the .SetLoop() function (or 1 if using the default).

s.SetReverse(bool)

Defaults to false

Configures the sequence to run in "reverse" or not.

• When yoyo is false:
  • If reverse is false, the sequence will run forward and will loop back to the beginning if available
  • If reverse is true, the sequence will run backward and will loop back to the end if available
• When yoyo is true:
  • The sequence will run according to normal yoyo logic. If a sequence has gone from the start to the end, and is coming back to the start (reverse is true) and you set reverse to false, then the sequence will start heading towards the end again. When it reaches the end it will simply yoyo as expected. The inverse is also true, if the sequence is heading to the end and you reverse it before the end, it'll simply head toward the start and if it reaches the start it will consume a loop and, if possible, start again.

s.Add(tweens ...*Tween)

Adds the tweens provided, in order, at the end of the existing tween list

s.Remove(index)

Removes the tween at the desired index. If you call .Remove() on an index out of bounds, nothing happens.

Easing functions

Easing functions are functions that express how slow/fast the interpolation happens in tween.

Gween comes with 45 default easing functions already built-in (adapted from Enrique García Cota's easing library).

The easing functions can be found in the ease package.

They can be divided into several families:

• linear is the simplest easing function, straight from one value to the other.
• quad, cubic, quart, quint, expo, sine and circle are all "smooth" curves that will make transitions look natural.
• The back family starts by moving the interpolation slightly "backwards" before moving it forward.
• The bounce family simulates the motion of an object bouncing.
• The elastic family simulates inertia in the easing, like an elastic gum.

Each family (except linear) has 4 variants:

• In starts slow, and accelerates at the end
• Out starts fast, and decelerates at the end
• InOut starts and ends slow, but it's fast in the middle
• OutIn starts and ends fast, but it's slow in the middle

family	in	out	inOut	outIn
Linear	Linear	Linear	Linear	Linear
Quad	InQuad	OutQuad	InOutQuad	OutInQuad
Cubic	InCubic	OutCubic	InOutCubic	OutInCubic
Quart	InQuart	OutQuart	InOutQuart	OutInQuart
Quint	InQuint	OutQuint	InOutQuint	OutInQuint
Expo	InExpo	OutExpo	InOutExpo	OutInExpo
Sine	InSine	OutSine	InOutSine	OutInSine
Circ	InCirc	OutCirc	InOutCirc	OutInCirc
Back	InBack	OutBack	InOutBack	OutInBack
Bounce	InBounce	OutBounce	InOutBounce	OutInBounce
Elastic	InElastic	OutElastic	InOutElastic	OutInElastic

Custom easing functions

You are not limited to gween's easing functions; if you pass a function parameter in the easing, it will be used.

The passed function will need to suite the TweenFunc interface: func(t, b, c, d float32) float32

• t (time): starts in 0 and usually moves towards duration
• b (begin): initial value of the of the property being eased.
• c (change): ending value of the property - starting value of the property
• d (duration): total duration of the tween

And must return the new value after the interpolation occurs.

Here's an example using a custom easing.

labelTween := tween.new(0, 300, 4, func(t, b, c, d) float32 {
  return c*t/d + b // linear ease
})

Credits

The easing functions have been translated from Enrique García Cota's project in

https://github.com/kikito/tween.lua

See the LICENSE file for details.

Documentation

Overview

Package gween provides the Tween struct that allows an easing function to be animated over time. This can be used in tandem with the ease package to provide the easing functions.

Index

• type Sequence
  • func NewSequence(tweens ...*Tween) *Sequence
  • func (seq *Sequence) Add(tweens ...*Tween)
  • func (seq *Sequence) HasTweens() bool
  • func (seq *Sequence) Index() int
  • func (seq *Sequence) Remove(index int)
  • func (seq *Sequence) Reset()
  • func (seq *Sequence) Reverse() bool
  • func (seq *Sequence) SetIndex(index int)
  • func (seq *Sequence) SetLoop(amount int)
  • func (seq *Sequence) SetReverse(r bool)
  • func (seq *Sequence) SetYoyo(willYoyo bool)
  • func (seq *Sequence) Update(dt float32) (value float32, tweenComplete, sequenceComplete bool)
• type Tween
  • func New(begin, end, duration float32, easing ease.TweenFunc) *Tween
  • func (tween *Tween) Reset()
  • func (tween *Tween) Set(time float32) (current float32, isFinished bool)
  • func (tween *Tween) Update(dt float32) (current float32, isFinished bool)

Types

type Sequence

type Sequence struct {
	Tweens []*Tween
	// contains filtered or unexported fields
}

Sequence represents a sequence of Tweens, executed one after the other.

func NewSequence

func NewSequence(tweens ...*Tween) *Sequence

NewSequence returns a new Sequence object.

func (*Sequence) Add

func (seq *Sequence) Add(tweens ...*Tween)

Add adds one or more Tweens in order to the Sequence.

func (*Sequence) HasTweens

func (seq *Sequence) HasTweens() bool

HasTweens returns whether the Sequence is populated with Tweens or not.

func (*Sequence) Index

func (seq *Sequence) Index() int

Index returns the current index of the Sequence. Note that this can exceed the number of Tweens in the Sequence.

func (*Sequence) Remove

func (seq *Sequence) Remove(index int)

Remove removes a Tween of the specified index from the Sequence.

func (*Sequence) Reset

func (seq *Sequence) Reset()

Reset resets the Sequence, resetting all Tweens and setting the Sequence's index back to 0.

func (*Sequence) Reverse

func (seq *Sequence) Reverse() bool

Reverse returns whether the Sequence currently running in reverse.

func (*Sequence) SetIndex

func (seq *Sequence) SetIndex(index int)

SetIndex sets the current index of the Sequence, influencing which Tween is active at any given time.

func (*Sequence) SetLoop

func (seq *Sequence) SetLoop(amount int)

SetLoop sets the default loop and the current remaining loops

func (*Sequence) SetReverse

func (seq *Sequence) SetReverse(r bool)

SetReverse sets whether the Sequence will start running in reverse.

func (*Sequence) SetYoyo

func (seq *Sequence) SetYoyo(willYoyo bool)

SetYoyo sets whether the Sequence should yoyo off of the end of the last Tween and complete at the beginning of the first Tween

func (*Sequence) Update

func (seq *Sequence) Update(dt float32) (value float32, tweenComplete, sequenceComplete bool)

Update updates the currently active Tween in the Sequence; once that Tween is done, the Sequence moves onto the next one. Update() returns the current Tween's output, whether that Tween is complete, and whether the entire Sequence was completed during this Update.

type Tween

type Tween struct {
	Overflow float32
	// contains filtered or unexported fields
}

Tween encapsulates the easing function along with timing data. This allows a ease.TweenFunc to be used to be easily animated.

func New

func New(begin, end, duration float32, easing ease.TweenFunc) *Tween

New will return a new Tween when passed a beginning and end value, the duration of the tween and the easing function to animate between the two values. The easing function can be one of the provided easing functions from the ease package or you can provide one of your own.

func (*Tween) Reset

func (tween *Tween) Reset()

Reset will set the Tween to the beginning of the two values.

func (*Tween) Set

func (tween *Tween) Set(time float32) (current float32, isFinished bool)

Set will set the current time along the duration of the tween. It will then return the current value as well as a boolean to determine if the tween is finished.

func (*Tween) Update

func (tween *Tween) Update(dt float32) (current float32, isFinished bool)

Update will increment the timer of the Tween and ease the value. It will then return the current value as well as a bool to mark if the tween is finished or not.