Description

An oscillator is an optional interpolator that runs t from [easing(0), easing(1)] and the usually outputs a value from [-1, 1] 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 oscillators. Unlike oscillators, the oscillators have their value stored in the Action Link, allowing to link the end value to the next animation.

An oscillator if it's used together with an easing will if it's in the same dimension deform the wave and if it's in different dimensions the easing will define the speed of oscillator.

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
}

One type of oscillators are pulsars.
Pulsars only have energy during a certain amount of time, the rest of the time are motionless.

Core oscillators

WARNING! In the ABeamer 2.x these core oscillators will move core-oscillators plugin.
To prevent breaking changes include now the js script core-oscillators.js on the html file.

ABeamer has the following core oscillators:

  • harmonic - it generates a sinusoidal function that repeats it self every duration / cycles.
    see: animate-oscillator.

  • damped - it's a sinusoidal function that reduces its amplitude due friction in every cycle.
    To reduce the user's effort, ABeamer uses cycles parameter to compute the friction.

  • pulsar - outside the range of [midpoint - spread, midpoint + spread] it will return 0, and inside the range will generate a function depending of the parameter type:

    • normal - a bell shape curve. this is the default type.
    • sine - a sinusoidal function.
    • random - a random value within [-1, 1].
    • positive-random - a random value with [0, 1].
      see: animate-pulsar.
 

API

OscillatorFunc

public export type

export type OscillatorFunc = (t: number, params: OscillatorParams,
    args?: ABeamerArgs) => number;

Defines the type of a oscillator function.
An oscillator function is an interpolator that runs from [0, 1].
Usually outputs a value from [-1, 1] but other values are also possible.
An oscillator is mostly used to rotate an element returning to the original position.

OscillatorHandler

public export type

export type OscillatorHandler = OscillatorName | number | ExprString
    | OscillatorFunc | EasingFunc;

Defines the oscillator type, which is either string representing a predefined oscillator function or a custom function (see oscillator function) The oscillator function interpolates from [0, 1].

OscillatorParams

public export type

export type OscillatorParams = AnyParams;

Defines the Base parameters for every oscillator function.
At the moment no parameter is required, but it can change in the future.

 

Oscillator

public export interface

export interface Oscillator{ }

Oscillator parameters defined in an Animation Property.

Oscillator.handler

public property [Oscillator]

handler: OscillatorHandler;

Defines an Oscillator by Name, Expression or Code Handler

Oscillator.params

public property [Oscillator]

params?: AnyParams
    | HarmonicOscillatorParams
    | DampedOscillatorParams
    | PulsarOscillatorParams;

Params passed to the Oscillator. Depends on the Oscillator Type

NegativeFunc

public export type

export type NegativeFunc = (t: number) => number;

Function used to define what to do when a value is negative.

 

HarmonicOscillatorParams

public export interface

export interface HarmonicOscillatorParams extends OscillatorParams{ }

Params defined inside the props.oscillator.params, when props.oscillator = 'harmonic'

HarmonicOscillatorParams.cycles

public property [HarmonicOscillatorParams]

cycles?: number;

Defines the number of full cycles (positive arc+negative arc) contained during the duration period.
If negativeHander = abs, 1 cycle will have 2 arcs.

HarmonicOscillatorParams.negativeHander

public property [HarmonicOscillatorParams]

negativeHander?: NegativeBuiltInFuncs | string | NegativeFunc;

Function used to define what to do when a value is negative.

HarmonicOscillatorParams.shift

public property [HarmonicOscillatorParams]

shift: number;

Allows to shift and scale the input of every oscillator.

 

DampedOscillatorParams

public export interface

export interface DampedOscillatorParams{ }

Params defined inside the props.oscillator.params, when props.oscillator = 'damped'

DampedOscillatorParams.frequency

public property [DampedOscillatorParams]

frequency?: number;

DampedOscillatorParams.friction

public property [DampedOscillatorParams]

friction?: number;

Defines how much energy the oscillator will lose from one cycle to the next.

DampedOscillatorParams.negativeHander

public property [DampedOscillatorParams]

negativeHander?: NegativeBuiltInFuncs | string | NegativeFunc;

Function used to define what to do when a value is negative.

 

PulsarOscillatorParams

public export interface

export interface PulsarOscillatorParams{ }

Params defined inside the props.oscillator.params, when props.oscillator = 'pulsar'

PulsarOscillatorParams.type

public property [PulsarOscillatorParams]

type?: PulsarType | string;

Type of pulsar defined by ID or string.

PulsarOscillatorParams.midpoint

public property [PulsarOscillatorParams]

midpoint?: number;

The point where the pulsar reaches it's maximum value.

PulsarOscillatorParams.spread

public property [PulsarOscillatorParams]

spread?: number;

The amplitude around midpoint where the pulsar begins to receive value.
The pulsar starts gaining energy at midpoint-spread, reaches the maximum value at midpoint and then decreases until reaches zero at midpoint+spread.