A calculator is a function which looks at the start and end values of a target feature and calculates the current value to apply.
In other words, the calculator function is what determines interpolated values to apply between keyframes.
Concert.js has four built-in calculator functions, allowing animation of several types of values.
The first thing to understand about calculator functions is that they are not the same thing as easing functions. Some animation libraries combine these two concepts, but they are really two separate things.
Concert.EasingFunctions.ConstantRate function would calculate that
if 25% of the time has passed, then the animation should be 25% of the way along,
and therefore return 0.25.
Concert.Calculators.Linear
(which is also the default if none is specified), just takes two numbers as the start and end values,
and returns a value in between according to the specified distance fraction.
That is, if the distance fraction calculated by the easing function is 0.5, the start value is 6,
and the end value is 8, then the Linear calculator will return 7 (halfway between the start and end).
Why does this have a separate function? Because not all things animated are simple numeric values. Concert.js can animate more complex things as well, like text content, or color values, which are not simple points along a number line.
There are four pre-built calculator functions:
Concert.Calculators.Color:
The Color calculator allows for smoothly animating color transitions, including alpha channel (transparency) values.
This function takes start and end values in the form of CSS color style value strings, specified
in any of hex, rgb, rgba, hsl, or hsla format (start and end values must be in the same format as each other).
It returns a color string in the same format, interpolated between the start and end values.
Concert.Calculators.Discrete:
The Discrete calculator can take any type of start and end value. It does no interpolation at all,
simply returning the start value if the transformation hasn't reached the end yet,
or the end value if it has. This calculator is good for things like changing text strings,
where interpolation makes no sense, or for animating numeric values that are meant to jump
from one value to another rather than be interpolated.
Concert.Calculators.Linear:
The Linear calculator simply calculates a linear interpolation between two numeric values.
Concert.Calculators.Rotational:
The Rotational calculator calculates a set of coordinates resulting from rotational motion.
Its start and end values are objects that define the start and end points of rotational motion,
and the calculator function will interpolate between those, returning coordinates in the form [left, top].
Below is an example that uses all four:
const Sun = document.getElementById("Sun"),
Neptune = document.getElementById("Neptune"),
OrbitTime = 2000, Orbits = 4,
CaptionBox = document.getElementById("Caption");
let animations =
[
{
target: Neptune,
feature: ["left", "top"],
unit: "px",
applicator: Concert.Applicators.Style,
calculator: Concert.Calculators.Rotational,
keyframes:
{
times: [0, Orbits * OrbitTime],
values:
[
{
centerX: 240, centerY: 130,
radius: 100, angle: 0,
offsetX: -10, offsetY: -10
},
{
centerX: 240, centerY: 130,
radius: 100, angle: Orbits * 2 * Math.PI,
offsetX: -10, offsetY: -10
}
]
}
},
{
target: Sun,
feature: ["left", "top", "width", "height"],
unit: "px",
applicator: Concert.Applicators.Style,
calculator: Concert.Calculators.Linear,
keyframes:
{
times: [OrbitTime, 2 * OrbitTime, 3 * OrbitTime],
values:
[
[215, 105, 50, 50],
[220, 110, 40, 40],
[185, 75, 110, 110]
]
}
},
{
target: Sun,
feature: "background-color",
unit: null,
applicator: Concert.Applicators.Style,
calculator: Concert.Calculators.Color,
keyframes:
{
times: [OrbitTime, 2 * OrbitTime, 3 * OrbitTime],
values: ["#ffff00", "#ffffcc", "#aa0000"]
}
},
{
target: CaptionBox,
feature: "innerHTML",
applicator: Concert.Applicators.Property,
calculator: Concert.Calculators.Discrete,
keyframes:
{
times: [0, OrbitTime, 3 * OrbitTime],
values: ["Main Sequence Star", "Transition", "Red Giant"]
}
}
];
let sequence = new Concert.Sequence();
sequence.addTransformations(animations);
document.getElementById("GoButton").onclick =
function () { sequence.begin(); };
The above code defines four distinct animations.
The first applies to a div with the ID "Neptune".
It modifies the left and top CSS properties,
and it does so using the Rotational calculator.
When run, this causes the div to move in a rotational pattern around the defined center point.
You may have noticed that the keyframe values given to it include 6 properties.
All of them can be animated. Here we only are animating the angle,
but it is possible to animate the center point, the radius, and the offset values as well.
(The offsetX and offsetY values are adjustments added to the final, calculated coordinates.
Remember that CSS positions define an element's top, left corner. Often what you really want
in rotational motion is not to orbit the top, left corner of an object around a center point,
but to orbit the center of that object around the center point. The offset values move the calculator's
output over and therefore can adjust for that problem.)
The second animation uses the Linear calculator to adjust four style properties
of the "Sun" object: left, top, width, and height.
This is very similar to animations we've seen in previous steps of this tutorial.
The third animation introduces the Color calculator.
This one modifies the background-color style of the "Sun" object.
Three keyframes are defined. At the first, the color is "#ffff00" (yellow).
Between the first and second keyframes, the color will gradually fade to the second value: "#ffffcc" (whitish-yellow),
and then finally between the second and third keyframes the color fades to "#aa0000" (red).
If we preferred, we could have used "rgb(255, 255, 0)" or rgba, hsl, or hsla equivalents instead.
The fourth animation uses the Discrete calculator.
This simply maintains each value unchanged until the next keyframe hits,
then applies the next value and maintains that, and so on.
Note: If you're paying attention closely, you'll have spotted that this transformation definition
also uses a new applicator, Concert.Applicators.Property.
This is needed for reasons that will become clear in the next tutorial step,
where applicator functions are discussed.
You are not limited to the built-in calculator functions. As with easing functions, user-provided calculator functions are easy to integrate with Concert.js. If you wish to calculate and apply complex numbers, object values, arrays of values, calculate values based on dynamically obtained values from user input, or accomplish some other task needed for your animation, you can supply your own function used for calculations.
A calculator function is any function with the following signature:
calculatorFunction(distanceFraction, startValue, endValue, addlProperties)
The distance fraction is a numeric value where 0 is the starting point (where the start value should be returned),
and 1 is end ending point (where the end value should be returned). Use any method you like for generating
the in-between value; just make sure that the value returned is one that the applicator function in use handles properly.
(Applicator functions are discussed in the next step of this tutorial.)
It is also possible to attach additional, custom properties to a sequence object or to the transformations within it,
in the case where some kind of extra data is needed to carry out the animation.
Those additional properties, if present, will be passed into any custom calculator function using the addlProperties argument.
Custom calculators can work any way you like. Just remember that they can be called many times per second in a running animation, so how quickly they run can have an effect on how smoothly your animation runs.
Reference documentation links for items covered in this step of the tutorial: