Fluid 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:

require 'vfx'

Utility Functions

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, 0.8),
    vfx.zoomOut(Icon.viewport, 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.
time	A timestamp indicating when the effect started.

vfx.fadeIn()

vfx.fadeIn(Viewport, Seconds, Delay, Callback)

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, Seconds, Delay, Callback)

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, Seconds, Delay, Intensity, Callback)

'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.

vfx.wipe()

vfx.wipe(Viewport, Seconds, Delay, Style, { 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'.

Example usage:

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

vfx.zoomIn()

vfx.zoomIn(Viewport, Seconds, Delay, Callback)

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, Seconds, Delay, Callback)

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.