Description

Defines how a list of elements (HTML Element, SVG element and Virtual Element), inside a Scene defined by Selector will have a list of properties (left, src, color, font-size, ...) modified over time.

Animations are added in parallel, via addAnimation, and in series via addSerialAnimations.
Although, the animations that are added in parallel, they can be Off-Sync via position parameter.

An animation has an Animation Interpolator that passes a t parameter from Start Value to Value through the Animation Pipeline.

An animation doesn't communicates direct with an HTMLElement attributes, instead uses an Adapter to serve as an interface, allowing for an animation property to map into different type of Elements and to map an animation property into multiple element properties such Dual Properties.

Tasks which are also added via addAnimation and allow to create complex animations and special effects.

 

API

BypassMode

public export type

export type BypassMode = 0 | 1 | 2;

FuncParams

public export type

export type FuncParams = AnyParams;

Base parameters used by any Animation Function.

ExprName

public export type

export type ExprName = ExprString;

A ExprName is used for motion handlers, mostly for easings, to have dynamic names.
Since an expression can be used to interpolate, by using expressions starting with '==', it will compute immediately the expression and the output must the motion name.
example: = 'easeIn' + iff(frameWidth < 100, 'Quad', 'Cubic')

 

AnimationCommonParams

public export interface

export interface AnimationCommonParams{ }

Defines parameters used both by Animation and AnimationProp.
The AnimationProp overrides the parameters defined by Animation.
This way, an animation can have parameters for all animation properties and some animation properties can have different parameters.
The duration parameter defined in the animation property

AnimationCommonParams.enabled

public property [AnimationCommonParams]

enabled?: boolean;

If it's false, it will bypass the animation or property.

AnimationCommonParams.advance

public property [AnimationCommonParams]

advance?: boolean;

A Scene.addAnimations runs its list of animations and properties in parallel, and at the end of last animation it moves the position forward.
Setting the advance:
1. To true of an animation property will move forward the position for the next property animation, but not the animation.
The property of each element moves independently.
2. To true of an animation that isn't the last one, will move forward for the next animation within the list.
The value used with the maximum of all the elements of the all the properties of the previous animation.
3. To false of the last animation, it won't move forward at the end.

AnimationCommonParams.duration

public property [AnimationCommonParams]

duration?: TimeHandler;

Defines the duration of the animation of a single cycle in terms of frames, seconds, minutes or milliseconds.
The total duration is duration*(iterationCount + 1).
In case of numerical values, ABeamer uses defaultUnit
to known what kind of unit is it.

see: iterationCount.
example: '1s'
example: '40ms'
example: '20%' (use only on the animation property duration)
example: '5fps'
example: 50
example: 2.5 (use only if the DefaultUnit is 's' or 'ms')
example: (args) => '2s' (JavaScript functions aren't teleportable)
example: '=round(fps/2)'

AnimationCommonParams.position

public property [AnimationCommonParams]

position?: TimeHandler;

Allows to off-sync the starting point of an animation.
Use +, - for relative positions.
Prefer relative positions over absolute positions.
Use only if you need to off-sync an animation.
Overlapping property animations isn't supported.
example: '-10fps' (starts the animation 10 frames before the expected starting point)
example: '+2ms' (starts the animation 2 milliseconds after the expected starting point
example: (args) => '4ms' (JavaScript functions aren't teleportable)

AnimationCommonParams.easing

public property [AnimationCommonParams]

easing?: EasingHandler;

An easing is a interpolator runs t from [0, 1], where t=0 is the first frame and t=1 the last frame of the animation.
This interpolator can be viewed as the speed interpolator and its the first one in the Animation Pipeline.
The output value will be used to feed the oscillator.
Usually outputs a value from [0, 1] but other values are also possible.

This interpolator can be used outside physical motion (left/right/top/bottom).
In cases of textual property, such as color, text, src, the easing will define how quickly those values will change among a list defined valueText or by using valueFormat.
In this case, the startValue and value should be between [0, 1].
Setting a startValue higher than value, will reverse the direction of the changes.

The easing can also be used to define the speed of the changes of multi-parameter properties, such as text-shadow, by using as an input of a valueFormat.

This is the first stage of the Animation Pipeline.
The output value will be used to feed the oscillator.

ABeamer includes a list of the most common easings by bundling the jquery.easing plugin.
More can be added via plugins.

An easing can be defined by:
1. Name - It will use the list of easings predefined or added via plugins.
2. Expression - It evaluate the expression for each frame, passing the variable t.
3. Code Handler - This function will receive the variable t.

WARNING Code Handlers aren't teleported, therefore it can't be used in remote rendering.
default: 'linear'
see: easings.

AnimationCommonParams.oscillator

public property [AnimationCommonParams]

oscillator?: Oscillator;

An oscillator is an optional interpolator that runs t from [easing(0), easing(1)] and the usually outputs a value from [-Amplitude, Amplitude] where usually f(0) = 0 and f(1) = 0.
Its output will be generate v = valueStart + (value - valueStart) * oscillator(easing(t))
and then will be injected into a path as input.

An oscillator has the following usages:

  1. A rotational movement, where the oscillator defines the rotation and the easing the defines the speed.

  2. Flashing elements, where an element changes its opacity or text-shadow, and these values oscillate between [0, 1].

  3. Uni-dimensional paths. Unlike paths, the oscillators have their value stored in the Action Link, allowing to link the end value to the next animation.

The oscillators shares the namespace with easings, allowing any easing function to operate also as a oscillator.
Since the main function of an oscillator is to return to its original position at the end of the animation cycle, when an easing is used as an oscillator the best is to use the following:

{ iterationCount: 2,
  direction: alternate
}

An oscillator can be defined by:
1. Name - It will use the list of easings and oscillator predefined or added via plugins.
2. Expression - It evaluate the expression for each frame, passing the variable t.
3. Code Handler - This function will receive the variable t.

WARNING Code Handlers aren't teleported, therefore it can't be used in remote rendering.

AnimationCommonParams.path

public property [AnimationCommonParams]

path?: Path;

AnimationCommonParams.itemDelayDuration

public property [AnimationCommonParams]

itemDelayDuration?: TimeHandler;

Delay of the start of the animation between 2 elements defined inside the selector.
The total duration of the animation will be: duration+count*itemDelayDuration.
see: itemDelayGrouping.

AnimationCommonParams.itemDelayGrouping

public property [AnimationCommonParams]

itemDelayGrouping?: uint;

Applies a modulus division to the elements defined in the selector when it relates the itemDelayDuration.
A itemDelayDuration=2, will make the odd elements to have the same itemDelayDuration.

AnimationCommonParams.itemDelayDisturbance

public property [AnimationCommonParams]

itemDelayDisturbance?: TimeHandler;

Applies a random changes with maximum of itemDelayDisturbance to the itemDelayDuration for each element defined by the selector.

AnimPropValue

public export type

export type AnimPropValue = string | number;

PropValueFunc

public export type

export type PropValueFunc = (args?: ABeamerArgs) => AnimPropValue;

PropValueStartHandler

public export type

export type PropValueStartHandler = AnimPropValue | int | ExprString | PropValueFunc;

PropValueHandler

public export type

export type PropValueHandler = PropValueStartHandler;

ValueTextFunc

public export type

export type ValueTextFunc = (t: number, args?: ABeamerArgs) => string;
 

AnimationProp

public export interface

export interface AnimationProp extends AnimationCommonParams{ }

AnimationProp.prop

public property [AnimationProp]

prop: PropName;

Defines the property name. The property corresponds to DOM style element or special properties

see: AnimationPropName.

AnimationProp.valueStart

public property [AnimationProp]

valueStart?: PropValueStartHandler;

Defines the starting value of an animation injected into the Animation Pipeline (easing➝oscillator➝path|valueText➝valueFormat).
Easing interpolates from valueStart to value.

Use only if:
1. ABeamer can't get the value from the element property.
2. There is no Action Link or you want to have a different start value.
3. Handle virtual elements.

  • Always set this value CSS transforms, since ABeamer doesn't computes the CSS transform.
  • For pixels, all write text with 'px' suffix unless is defined valueFormat.
  • To interpolate textual values, usually set valueStart=0.
  • It supports expressions and Code Handlers.

WARNING Code Handlers aren't teleported, therefore it can't be used in remote rendering.
example: 10
example: '4px'
example: 'true'
example: '=frameCount'
If valueFormat='%dpx'
example: 4

AnimationProp.value

public property [AnimationProp]

value?: PropValueHandler;

Defines the end numerical value into the Animation Pipeline (easing->oscillator->path|valueText->valueFormat).
Easing interpolates from valueStart to value.

  • For pixels, use a numerical value.
  • Use textual properties, usually don't need to define this value since the default is 1.
  • To have a value relative to the starting value (valueStart or computed value), use '+value' or '-value'.
  • It supports expressions and Code Handlers.

WARNING Code Handlers aren't teleported, therefore it can't be used in remote rendering.
default: 1
example: '+10'
example: 100

AnimationProp.onSetValue

public property [AnimationProp]

onSetValue?(value: AnimPropValue, args?: ABeamerArgs): boolean;

This event is fired before modifying an element property during rending.
Use if you need to handle virtual elements.
or if you want to manually set an element value.
If returns false, ABeamer won't set the element property.

WARNING Events aren't teleported, therefore it can't be used in remote rendering.

AnimationProp.valueFormat

public property [AnimationProp]

valueFormat?: string;

Formats the value using the sprintf rules.
This is the last node in the computation pipeline.
It can format numerical values returned by the easing->oscillator, but also each value of a path and a value returning from valueText.
example: '%dpx %dpx 8px white'
example: 'rotateX(%fdeg)'
example: 'rotateX(%fdeg)'

AnimationProp.valueText

public property [AnimationProp]

valueText?: string[] | ExprString | ValueTextFunc;

Provides a list of textual values, expression or function to be interpolated.
This value is computed after easing, oscillator and path interpolators and round function.
Mutual exclusive with pixels, multi-dimension paths and booleans.

Used by textual properties such as color, url, font-family and text.

AnimationProp.waitFor

public property [AnimationProp]

waitFor?: WaitForList;

EXPERIMENTAL Waits for the adapter to be ready to deliver an asset before instructing the render to move to the next frame or give the server order to store the image.
Used to wait for loading images or sync with videos.

This feature is not implemented yet...Coming soon .

see: animate-video-sync.

AnimationProp.roundFunc

public property [AnimationProp]

roundFunc?: RoundFuncName;

Round function to apply after easing->oscillator->path.
If this value is not set, for pixels properties the round function will be used, for other properties there is no default round function.

AnimationProp.iterationCount

public property [AnimationProp]

iterationCount?: int;

Defines how many times the animation repeats itself.
Same as CSS animation-iteration-count.

see: animate-loop.
example: 1 (to run twice)
example: 3 (to run 4 times)

AnimationProp.direction

public property [AnimationProp]

direction?: uint | string;

Defines the direction of each iteration.
Same as CSS animation-direction.
example: 'alternate'
example: ABeamer.DI_ALTERNATE
example: ABeamer.DS_NORMAL

AnimationProp.bypassForwardMode

public property [AnimationProp]

bypassForwardMode?: BypassMode;

Defines how the frames should be bypassed in case of a flush or another forward motion outside the rendering process.
default: BP_FIRST_INSIDE

AnimationProp.bypassBackwardMode

public property [AnimationProp]

bypassBackwardMode?: BypassMode;

Defines how the frames should be bypassed in case of a flush or another backward motion outside the rendering process.
In a backward motion the first stage it's end point of animation.
default: BP_FIRST_INSIDE

 

Animation

public export interface

export interface Animation extends AnimationCommonParams{ }

Definition of the animation to be sent to the render pipeline.
Used by Scene.addAnimations.

Animation.tasks

public property [Animation]

tasks?: Task[];

Tasks allow to build complex animations and to avoid executing javascript code.

see: tasks.

Animation.selector

public property [Animation]

selector?: ElSelectorHandler;

css selector, JQuery, html elements, virtual selector or meta-selectors that defines the list of elements.
If strictMode is false, the empty selectors will be gracefully bypassed.

This field can be empty only if there is a setup task.

Animation.props

public property [Animation]

props?: AnimationProp[];

List of properties per animation.

see: AnimationProp.

Animations

public export type

export type Animations = Animation[];