Tiri VFX API

The VFX API provides a set of functions that can be used to apply animated effects to viewport objects. Each effect has a very specific purpose, and additional options allow tweaking of their behaviour. Taking advantage of the power in this API comes from chaining effects together to create complex, customised animations.

To load the VFX API:

import 'vfx'

Utility Functions

vfx.ease

Effects that animate a linear progress value can apply easing by passing an easing name, an easing function, or the easing option for vfx.wipe(). The built-in easing names are:

Name	Description
linear	Default linear progress.
inQuad	Quadratic acceleration.
outQuad	Quadratic deceleration.
inOutQuad	Quadratic acceleration and deceleration.
inCubic	Cubic acceleration.
outCubic	Cubic deceleration.
inOutCubic	Cubic acceleration and deceleration.

An easing function accepts a progress value from 0.0 to 1.0 and returns the adjusted progress value. For example:

vfx.zoomIn(Icon.viewport, { seconds=0.4, easing='outCubic' })
vfx.rotate(Icon.viewport, { seconds=0.8, easing=vfx.ease.inOutQuad })

vfx.chain()

vfx.chain({ Effects, ... }, Callback)

Use chain() to activate a list of multiple Effects at the same time. Once all effects in the chain have finished processing, the Callback is executed.

In the example below, the rotate and zoomOut effects are applied together to shrink an icon. When the animation has completed, the icon will no longer be visible and can be terminated via the Callback function.

effect = vfx.chain({
    vfx.rotate(Icon.viewport, { seconds=0.8 }),
    vfx.zoomOut(Icon.viewport, { seconds=0.8 })
}, function()
    Icon.viewport.free()
    Icon.viewport = nil
end)

Primary Functions

For the following effects, the Callback function prototype is function(State) and it will be called on completion of the effect. The State is a table providing the following key-values:

Key	Description
name	Matches the name of the effect function.
seconds	The original number of Seconds specified by the client.
delay	The original Delay specified by the client.
easing	The easing curve applied to the effect, if any.
time	A timestamp indicating when the effect started.

Common options are:

Option	Description
seconds	Maximum number of seconds for the effect to complete. Defaults to 1.0.
delay	Delay before the effect starts, measured in seconds. Defaults to 0.
callback	Function called on completion with the effect State.
easing	Built-in easing name or custom easing function.

Effect-specific options include intensity for vfx.shake() and style, segments, rotate, cx, cy, and invert for vfx.wipe().

vfx.fadeIn()

vfx.fadeIn(Viewport, { Options })

Fades a Viewport into the display by adjusting the opacity level. Seconds specifies the maximum number of seconds for the effect to complete. Delay delays the initial start of the effect, measured in seconds.

vfx.rotate()

vfx.rotate(Viewport, { Options })

Rotate the Viewport 360 degrees within the allotted time. This feature is typically chained for use with other effects. Seconds specifies the maximum number of seconds for the effect to complete. Delay delays the initial start of the effect, measured in seconds.

vfx.shake()

vfx.shake(Viewport, { Options })

'Shake' a Viewport by applying an alternating rotation around its center.Seconds specifies the maximum number of seconds for the effect to complete. Delay delays the initial start of the effect, measured in seconds. Intensity is between 0.1 and 2.0 and affects the number of shakes and maximum angle of rotation.

If Easing is supplied, it is applied as an amplitude envelope so that the shake naturally settles towards the end of the effect.

vfx.wipe()

vfx.wipe(Viewport, { Options })

Use this 'screen wipe' effect to display or hide a viewport using animated masks. Seconds specifies the maximum number of seconds for the effect to complete. Delay delays the initial start of the effect, measured in seconds. Style declares the type of wipe that will be performed and this will effect the Options that are available.

The following table lists the available styles and their option values. Note that angles are always measured in degrees.

Style	Description
shutter	Draw a basic shutter effect that looks similar to a window blind being adjusted. The segments option controls the total number of bars that will be drawn; rotate is an angle that adjusts the rotation of the bars.
simple	A straight-forward 'top-down' wipe that comes with a rotate option to adjust the angle.
radial	Draw a series of concentric circles to create a ripple effect. Options are: segments defines the total number of concentric circles; cx and cy define the point of origin for the circles.
spiral	Draw a spiral that radiates from a center point. cx and cy define the point of origin; segments affects the number of full rotations that can be completed within the avaialable space. It is recommended that segments is kept to a low value of 1 to 3.
clock	Draw a clock hand that fills in the viewport while rotating around the center point.

By default, all wipes are 'wipe-in' unless the option invert=true is used to run the animation backwards, causing a 'wipe-out'. An easing curve can be supplied as Options.easing.

Example usage:

vfx.wipe(Icon.viewport, { seconds=1.2, delay=0.2, style='radial', cx=0.5, cy=0.5, segments=4, easing='outCubic' })

vfx.zoomIn()

vfx.zoomIn(Viewport, { Options })

Scale the Viewport from nothing to full-size within the allotted time. Seconds specifies the maximum number of seconds for the effect to complete. Delay delays the initial start of the effect, measured in seconds.

vfx.zoomOut()

vfx.zoomOut(Viewport, { Options })

Scale the Viewport from full-size to nothing within the allotted time. Seconds specifies the maximum number of seconds for the effect to complete. Delay delays the initial start of the effect, measured in seconds.