Timing model
This section describes and defines the behavior of the Web Animations
timing model.
Timing events, however, which are also a feature of the timing
model, are described separately in .
Timing model concepts
In Web Animations timing is based on a hierarchy of time relationships
between timing nodes.
Parent nodes provide timing information to their child nodes in the form
of time values.
A time value is a real number which nominally represents
a number of seconds from some moment.
The connection between time values and wall-clock seconds may be
obscured by any number of transformations applied to the value as it
passes through the time hierarchy.
In the future we may have timelines that are based on UI gestures in
which case the connection between time values and seconds will be
weakened even further.
Periodically, the user agent will trigger an update to the timing model
in a process called sampling.
On each sample the time values of each timing node are
updated.
A more precise definition of when the model is updated when scripting is
involved is provided in .
The global clock
At the root of the Web Animations timing hierarchy is the global
clock.
The global clock is a source of monotonically increasing
time values unaffected by adjustments to the system clock.
The time values produced by the global clock represent
wall-clock seconds from an unspecified historical moment.
Because the zero time of the global clock is not specified,
the absolute values of the time values produced by the global
clock are not significant, only their rate of change.
Note that the global clock is not exposed in the programming interface and nor is it
expected to be exposed by markup.
As a result the moment from which global clock time values
are measured, that is, the zero time of the clock, is allowed to be
implementation-dependent.
One user agent may measure the number of seconds since the the user
agent was loaded whilst another may use the time when the device was
started.
Both approaches are acceptable and produce no observable difference
in the output of the model.
Timelines
A timeline provides a source of time values for the
purpose of synchronization.
Typically, a timeline is tied to the global clock such
that its absolute time is calculated as a fixed offset from the time of
the global clock.
This offset is established by designating some moment as the timeline's
zero time and recording the time value of the
global clock at that moment.
At subsequent moments, the time value of the timeline is
calculated as the difference between the current time value of
the global clock and the value recorded at the zero time.
Note that we anticipate that other types of timelines may be introduced
in the future that are not tied to the global clock.
For example, a timeline whose time values correspond to UI gestures.
Since a timeline may be defined relative to a moment that has yet
to occur, it may not always be able to return a meaningful time
value.
A timeline is considered to be not started when it is
in such a state that it cannot produce a time value.
The document timeline
Each document has a timeline called the document
timeline whose time value at a given moment is calculated
as a fixed offset from the global clock such that its zero
time corresponds to the moment immediately prior to dispatching
the load event of the document.
Prior to this moment, the document timeline is not
started.
For documents that support the concept of current document readiness, this is the moment after the current document readiness has changed to "complete" but
before dispatching the load event.
For user agents that support Navigation Timing [[NAVIGATION-TIMING]],
this occurs between the domComplete and
loadEventStart timings.
This is not correct.
We need a means to start animations prior to document load.
Since the document timeline is tied to the global clock
by a fixed offset, time values reported by the document
timeline increase monotonically.
Furthermore, since no scaling is applied, these time values
are proportional to wall-clock seconds.
Players
A player connects a single timed item, called its
source content, to a timeline and provides playback
control.
A player records the time value of its timeline
at which its source content is scheduled to begin
as the player start time.
When a player is created, it is assigned a globally unique
sequence number called the player sequence number.
This number is used to resolve the sort order of players that have the
same start time for a variety of
situations such as combining animations, queuing events, and returning
the list of current players.
Seeking, pausing and limiting
Seeking, pausing and limiting a player are closely related and are
described here together.
Seeking, pausing and limiting properties
Players track three properties related to seeking,
pausing and limiting.
- time lag
-
The offset from a player's scheduled current time as defined by
its start time, and its actual
current time after accounting for the effects of seeking,
pausing, and limiting.
The time lag is initially zero and is updated as per the
definition in .
- paused state
-
A boolean value that is true if the player is currently paused.
The paused state is initially false.
- hold time
-
The effective current time to maintain while the player is
paused or effectively paused because it has reached the end
of its source content and is limited.
When neither of these conditions apply, the hold time is
null.
The hold time is initially null.
In addition to these properties, implementations are required to
keep track of the last calculated value of the current time
in order to produce correct limiting behavior (see ).
It is possible to conflate the hold time with the previously
calculated current time provided proper care is taken to update the
stored value of the time lag.
For clarity, however, these two values are separated in the
following algorithms.
Is it actually the previously calculated value? Or the value
calculated on the previous sample / seek? Does it actually make any
practical difference?
A number of calculations for performing seeking, pausing and
limiting are defined to operate even when the associated
timeline is not started.
For such situations we define the effective timeline time
as the current time value of the timeline associated
with a player unless the timeline is not started, in
which case the effective timeline time is zero.
Calculating the time lag
The time lag value is both a stored and a calculated value.
When a player is paused or limited, the value is calculated
from the hold time.
When a player is not paused or limited, the stored value is used.
The stored value is initially zero, and is updated when the player
is unpaused, seeked, or becomes no longer limited.
The value of time lag at a given moment is calculated as
follows:
- Let the pause time lag be the result of evaluating
(effective timeline time - player start
time) × player playback rate -
hold time.
- Let the unlimited current time be the result of
evaluating the current time using the stored
value of the time lag.
- Let the source content end be the end time
of the player's source content.
If the player has no source content, let the
source content end be zero.
- The time lag is then calculated using the first matching
condition from below:
- If the paused state is true,
- Return the pause time lag.
- If the player playback rate < zero and
the unlimited current time ≤ zero,
-
- If the hold time is null,
let the hold time be zero.
- Return the result of evaluating the pause
time lag using the possibly updated hold
time.
- If the player playback rate > zero and
the unlimited current time ≥
source content end,
-
- If the hold time is null,
let the hold time be the maximum value of
the last calculated value of current time
and source content end.
If there is no previously calculated value of current
time or it is
null,
let the hold time be source content end.
- Return the result of evaluating the pause
time lag using the possibly updated hold
time.
- Otherwise,
-
- If the hold time is not null,
set the stored value of the
time lag to the pause time lag.
- Let the hold time be null.
- Return the stored value of the time lag.
Timed items
A timed item is an abstract term referring to a node in the
timing hierarchy.
Relationship between timed items and players
The source content of a player, if set, is a type of
timed item.
The source content of a player is said to be directly associated
with that player.
Timed items can be combined together into a hierarchy using
timing groups (see ).
Only the root timed item of such a hierarchy can be
directly associated with a player.
If a timed item that has a parent timing group is
designated as the source content of a player, the
timed item is removed from its parent timing group
before being associated with the player.
A timed item is associated with a player if it is
directly associated with a player or if it has an
ancestor timing group that is
directly associated with a player.
At a given moment, a timed item can be associated with at most one
player.
A timed item, item, is associated with
a timeline, timeline, if item is
associated with a player which, in turn, is associated with
timeline.
Types of timed items
This specification defines two types of timed item:
All types of timed item define a number of common properties
which are described in the following sections.
The active interval
Timed items define an active interval which is the
period of time during which the item is scheduled to produce its
effect with the exception of fill modes which apply outside
the active interval.
The lower bound of the active interval is defined by the
combination of the timed item's start
time and start delay
A timed item's start
time is the moment at which the parent timing group, if
any, has scheduled the timed item to begin.
It is expressed in inherited time.
In most cases, including the case when the timed item has no
parent timing group, the start
time is zero.
The singular exception is sequence timing groups which set the
start times of their children as
described in .
In addition to the start time,
a timed item also has a start delay which is an
offset from the start time.
Unlike the start time which is
determined by the parent timing group, the start delay
is a property of the timed item itself.
The lower bound of the active interval of a timed item,
expressed in inherited time space, is
the sum of the start time and the
start delay.
These definitions are incorporated in the calculation of the local
time (see ) and active time.
The length of the active interval is called the active
duration, the calculation of which is defined in .
Similar to the start delay, a timed item also has an
end delay which may be used to delay the start time
of the next sibling in a sequence timing group.
Should the end delay delay the end event too?
That is how SVG's min behavior works which is the reason we introduced
the end delay.
Fill behavior
The effect of a timed item when it is not in play is
determined by its fill mode.
The possible fill modes are:
- none,
- forwards,
- backwards, and
- both.
The normative definition of these modes is incorporated in the
calculation of the active time in .
Repeating
Iteration intervals
It is possible to specify that a timed item should repeat
a fixed number of times or indefinitely.
This repetition occurs within the active interval.
The span of time during which a single repetition takes place is
called an iteration interval.
Unlike the active interval, a timed item can have multiple
iteration intervals although typically only the interval
corresponding to the current iteration is of interest.
The length of a single iteration is called the iteration
duration.
The initial iteration duration of a timed item is simply its
intrinsic iteration duration.
The intrinsic iteration duration of a timed item is zero,
however some specific types of timed item such as timing groups
override this behavior and provide an alternative intrinsic duration
(see and ).
The iteration duration of a timed item may be set by the
author to represent a value other than the intrinsic iteration
duration.
Controlling iteration
The number of times a timed item repeats is called its
iteration count.
The iteration count is a real number greater than or equal to
zero.
The iteration count may also be positive infinity to represent
that the timed item repeats indefinitely.
In addition to the iteration count, timed items also
have an iteration start property which specifies an offset
into the series of iterations at which the timed item should
begin.
The iteration start is a finite real number greater than or
equal to zero.
The behavior of these parameters is defined in the calculations in .
Core timed item calculations
Transforming the local time
Calculating the active time
The active time is based on the local time
and start delay.
However, it is only defined when the timed item should
produce an output and hence depends on its fill mode and
phase as well as the phase of its parent timing group, if
any, as follows,
- If the timed item is in the before phase,
-
The result depends on the first matching condition from the
following,
- If the timed item has a parent timing group and
that parent timing group is in the after phase,
-
Return
null.
- If the fill mode is backwards or both,
- Return zero.
- Otherwise,
- Return
null.
- If the timed item is in the active phase,
-
The result depends on the first matching condition from the
following,
- If the timed item has a parent timing group and
that parent timing group is in the before phase,
and the fill mode of this timed item is none or forwards,
-
Return
null.
- If the timed item has a parent timing group and
that parent timing group is in the after phase,
and the fill mode of this timed item is none or backwards,
-
Return
null.
- Otherwise,
-
Return
local time - start delay.
- If the timed item is in the after phase,
-
The result depends on the first matching condition from the
following,
- If the timed item has a parent timing group and
that parent timing group is in the before phase,
-
Return
null.
- If the fill mode is forwards or both,
- Return the active duration.
- Otherwise,
- Return
null.
- Otherwise (the local time is
null),
-
Return
null.
Direction control
Timed items may also be configured to run iterations in
alternative directions using direction control.
For this purpose, timed items have a playback
direction parameter which takes one of the following values:
- normal,
- reverse,
- alternate, or
- alternate-reverse.
The semantics of these values are incorporated into the calculation of
the directed time which follows.
Calculating the directed time
The directed time is calculated from the iteration
time using the following steps:
- If the iteration time is
null, return
null.
-
Calculate the current direction using the first
matching condition from the following list:
-
If playback direction is
normal,
- Let the current direction be forwards.
-
If playback direction is
reverse,
- Let the current direction be reverse.
-
Otherwise,
-
-
Let d be the current iteration.
-
If playback direction is
alternate-reverse increment
d by 1.
-
There used to be a step here which seemed to be adding
special handling for filling when the item ends on
a repeat boundary but it seems like that is taken care
of by the calcuation of iteration time and
current iteration.
Is anything actually needed here?
-
If
d % 2 == 0, let the
current direction be forwards, otherwise let
the current direction be reverse.
-
If the current direction is forwards then return
the iteration time.
Otherwise, return the iteration duration
- iteration time.
Time transformations
Timing functions
A timing function takes an input time fraction in the range
[0, 1] and produces an output time fraction whose range is unbounded
(i.e. positive and negative infinity are permitted).
Timed items have one timing function associated with
them.
The default timing function is the linear timing
function whose output is identical to its input.
The linear timing function can be represented by the string
“linear”.
The range of timing functions that may be applied to a given
timed item depends on the type of the timed item.
Currently, the set of timing functions allowed on a timing
group is not restricted.
This has raised concern about complexity of implementation and also
complexity of behavior with regards to fill modes and events.
As a result, allowing the full set of timing functions on timing
groups is considered at risk.
Alternatives are to either restrict timing functions on timing
groups to the linear timing function or to a set of
“simple” timing functions that have properties that
alleviate some of the concerns with the more complex timing
functions.
See section
2 of the discussion from August 2013.
Scaling using a cubic Bézier curve
A cubic Bézier timing function is a type of timing
function defined by four real numbers that specify the two control
points, P1 and P2, of a cubic Bézier curve whose
end points are fixed at (0, 0) and (1, 1).
The x coordinates of P1 and P2 are
restricted to the range [0, 1].
The evaluation of this curve is covered in many sources such as
[[FUND-COMP-GRAPHICS]].
A cubic Bézier timing function may be specified as a string
using the following syntax (using notation from [[!CSS3-VALUES]]):
<cubic-bezier-timing-function> =
ease | ease-in | ease-out | ease-in-out |
cubic-bezier(<number> <number>
<number>
<number>)
The meaning of each value is as follows:
- ease
-
Equivalent to cubic-bezier(0.25, 0.1, 0.25, 1).
- ease-in
-
Equivalent to cubic-bezier(0.42, 0, 1, 1).
- ease-out
-
Equivalent to cubic-bezier(0, 0, 0.58, 1).
- ease-in-out
-
Equivalent to cubic-bezier(0.42, 0, 0.58, 1).
- cubic-bezier(<number> <number> <number> <number>)
-
Specifies a cubic Bézier timing function.
The four numbers specify points P1 and P2 of
the curve as (x1, y1, x2, y2).
Both x values must be in the range [0, 1] or the definition is
invalid.
It has been proposed to extend cubic-bezier to allow
multiple segments, using syntax such as the following:
cubic-bezier( [ <number>{6} ; ]* <number>{4} )
(i.e. the curve starts at (0, 0); each segment is defined by six
numbers where the start point is the end of the previous segment and
the numbers define the two control points and the end point. The
last segment is defined by four numbers since the end point is fixed
at (1, 1).)
This would provide a simple and compact syntax for tools trying to
map arbitrary curves (e.g. bounce functions) to timing functions.
Timing in discrete steps
A step timing function is a type of timing function
that divides the input time into a specified number of intervals that
are equal in duration.
The output time, starting at zero, rises by an amount equal to the
interval duration once during each interval at the transition point
which may be either the start, midpoint, or end of the interval.
In keeping with Web Animations' model of endpoint exclusive
interval timing (see ), the output time at the transition point is
the time after applying the increase (i.e. the top of the
step) with the following exception.
When a transition point coincides with the end of the active
interval extra care must be taken to produce the correct result
when performing a fill.
To achieve this, when a step timing function is
applied to a timed item or applied to an animation
effect associated with a timed item, an additional
before flag is passed.
The value of the before flag is determined as follows:
- If the active time of the timed item is null, the before
flag is not set and these steps should be aborted.
- Determine the current direction using the procedure
defined in .
- If either the current direction is forwards or the timed item playback
rate ≥ 0 (but not when both conditions are true),
let going forwards be true, otherwise it is false.
- The before flag is set if the timed item is in the
before phase and going forwards is true;
or if the timed item is in the after phase and going
forwards is false.
When a step timing function is evaluated at a transition point, if
the before flag is set the result is the value before
applying the increase.
A step timing function may be specified as a string
using the following syntax:
<step-timing-function> =
step-start | step-middle | step-end |
steps(<integer>[,
[ start | middle | end ] ]?)
The meaning of each value is as follows:
- step-start
-
Equivalent to steps(1, start);
- step-middle
-
Equivalent to steps(1, middle);
- step-end
-
Equivalent to steps(1, end);
- steps(<integer>[, [ start | middle | end ] ]?)
-
Specifies a step timing function.
The first parameter specifies the number of intervals in the
function.
It must be a positive integer (greater than 0).
The second parameter, which is optional, specifies the point at
which the change of values occur within the interval.
If the second parameter is omitted, it is given the value end.
Animations
Animations are a kind of timed item
that apply an animation effect to an element or pseudo-element
such as ::before and ::first-line [[!SELECT]]
referred to as the animation target.
Animation model
Animation effects
An animation effect takes a time fraction and
a current iteration value and uses them to calculate an
intermediate animation value for its target properties. Each animation
may have at most one animation effect associated with it.
Since the result of an animation effect is based on the
time fraction and current iteration value, it is updated
whenever the timing model is sampled.
Note that changes to the timing model caused by using the programming interface do not cause
the animation model (and hence animation effects) to be updated
as described in .
Target properties
Each animation effect can have zero or more associated
target properties.
Target properties may be CSS properties
or DOM attributes.
If a given animation target has an attribute with the same name
as a CSS property, any target property is taken to refer to to
the CSS property.
If there ever exists a situation where we need to animate an attribute
with the same name as a property (other than a presentation
attribute [[SVG2]]) then we will need to introduce
a disambiguation strategy. Generally, however, such naming should be
avoided.
Procedures for animating properties
In order to animate a target property the following procedures
must be defined.
- interpolation —
given two target property values Vstart and
Vend, produces an intermediate value
Vres at a distance of p along the
interval between Vstart and
Vend such that
p = 0 produces Vstart and
p = 1 produces Vend.
The range of p is (−∞, ∞) due to the
effect of timing functions.
As a result, this procedure must also define extrapolation
behavior for p outside [0, 1].
- addition — given two
target property values
Va and Vb returns the
sum of the two properties, Vresult.
For addition that is not commutative (for example, matrix
multiplication) Va represents the first term
of the operation and Vb represents the
second.
- distance computation — given two target property
values Vstart and
Vend calculates some notion of scalar
distance between the values, distance.
While addition can often be
expressed in terms of the same weighted sum function used to define interpolation, this is not always
the case.
For example, interpolation of transform matrices involves
decomposing and interpolating the matrix components whilst addition
relies on matrix multiplication.
Specific animation behaviors
The specific procedures used for animating a given target
property are referred to as the property's animation
behavior.
The animation behavior of CSS properties is defined by the
"Animatable:" line in the summary of the property's definition or in
[[CSS3-TRANSITIONS]] for properties that lack a such a line.
The default animation behavior for CSS properties is "as
string". Should this be defined here or in CSS Animations Level 4?
For DOM attributes, the animation behavior is defined alongside
the attribute definition.
Unlike CSS properties, if such a definition is not provided the
default animation behavior is “not
animatable”.
Following is a series of pre-defined animation behaviors.
[[CSS3-TRANSITIONS]] provides further CSS-specific animation
behaviors.
For animation behaviors that do not define a specific procedure
for addition or which are defined as
not additive, the addition procedure is simply
Vres = Vb.
For animation behaviors that do not define a specific procedure
for distance computation or which are defined as not
paceable, the distance computation procedure is simply
distance = 1.
Animatable as color
A target property that is animatable as color has
the following animation behavior:
- interpolation:
as defined in [[CSS3-TRANSITIONS]].
- addition:
as with animatable as real number but performed on each
RGBA color component in premultiplied space.
Since negative color is not currently supported, clamping of
the channel values may be performed upon each addition or once
when composition is complete.
- distance computation:
sqrt((Rend
- Rstart)^2 + (Gend
- Gstart)^2 + (Bend
- Bstart)^2 + (Aend
- Astart)^2)
where <R|G|B|Astart|end>
represents the red, green, blue, or alpha channel of
Vstart or Vend
respectively.
Each value is normalized to the [0.0, 1.0] range and expressed
in premultiplied color space.
Should we call this “animatable as premultiplied RGBA additive
color in sRGB color space” instead?
Animatable as transform list
A target property that is animatable as transform
list has the following animation behavior:
For distance computation we previously defined it as
follows:
- Look only at the first component of the two lists
- If both are translate → euclidean distance
- If both are scale → absolute difference
- If both are rotate → absolute difference
- If both match but are something else → use linear
- If they don't match → use matrix decomposition and
euclidean distance between translate components
This seems really arbitrary, especially part 5.
Also, looking at only the first component seems odd.
Going through each component, working out the distance and then
getting the square of the distance also seems much more consistent
with what we do elsewhere.
Other animation behaviors
The set of animation behaviors defined here may be extended
by other specifications.
For example, properties with using the <image> type are
animated using the interpolation behavior defined in CSS Image
Values and Replaced Content
[[CSS4-IMAGES]].
There are a bunch of CSS properties for which distance (and in
some cases addition) is not defined or which need special
handling.
For example,
- font-stretch (an enum but handled like an integer)
- visibility (0 or 1 depending on if endpoints match or not)
- flex-grow and flex-shrink which allow animation only if one of
the endpoints is 0)
- value pairs, triples (use square distance)
- rects (use square distance)
- dash arrays (square distance but a bit weird due to
percentages)
- shadows (square distance of components)
- filters (undefined)
- background-position (special list handling needed)
- pair lists
Should we define these here or in the CSS Animation 4 spec?
Combining animations
The animation stack
Associated with each property targetted
by one or more animation effects is an animation
stack that establishes the relative priority of the animation
effects.
The relative priority of any two animation
effects, A and B, within an animation
stack is established by comparing the properties of the
animations applying A and B as follows:
- Let the associated player of an animation effect
be the player associated with the
animation that is applying the animation effect to
the property with which this animation stack is
associated.
- Sort A and B by applying the following
conditions in turn until the order is resolved,
- Sort A and B using any custom
animation priority specified for A and
B so that lower priorities sort first.
- Sort A and B by the player start
time of the associated player of each of
A and B converted to the time space of
the global clock so that earlier times sort first.
- Sort by the player sequence number so that lower
sequence numbers sort first.
- Sort A and B in tree order.
(By this point, A and B must have the
same player since otherwise the order would have been
resolved in the previous step.)
Animation effects that sort earlier have lower
priority.
The custom animation priority
Each animation effect has an associated numeric
custom animation priority that is used to provide
high-level control of animation priority for specifications layered
on top of Web Animations.
The initial value of the custom animation priority is zero.
Note that the custom animation priority is primarily
intended to be used to prioritize animation effects at
a high-level, such as to prioritize animations by type.
For example, it can be used to ensure that CSS Animations always
override CSS Transitions.
It is possible to control animation priority at a lower-level by
setting the player start time appropriately,
(possibly after making compensatory adjustments to the start
delay of the source content) or influencing the
player sequence number by controlling when players
are created.
Applying the composited result
The process for a applying a composited value depends on if the
target property refers to a CSS property or a DOM attribute.
Applying the composited result to a DOM attribute
DOM attributes are, unless otherwise specified, not
animatable.
For each attribute that has a specific animation behavior
associated with it, an attribute value to use when the attribute is
not specified or in error must be defined, referred to as the
lacuna value.
For example, SVG2 ([[SVG2]]) defines lacunae
values for its attributes.
The composited value calculated for a DOM attribute target
property is applied using the following process.
- Let the base value of the property be the value
specified for attribute in the DOM or,
if the attribute value is not specified in the DOM, the
lacuna value for that attribute.
- Establish the animation stack for the property (see ).
- Calculate the composited value of the animation
stack passing in the base value of the attribute
as the initial underlying value (see ).
- Record the composited value as the animated
attribute value of the attribute.
The animated attribute value does not replace the value of
the attribute in the DOM although it may be accessible via some
other interface.
For all intents and purposes other than interaction with DOM
interfaces, user agents must treat the animated attribute
value as the attribute value.
Keyframe animation effects
A keyframe animation effect is an animation effect
that produces intermediate animation values for its target
properties by interpolating between a series of property values
positioned at fractional offsets.
Each set of property values indexed by an offset is called
a keyframe.
The offset of a keyframe is a value
in the range [0, 1] or the special value null.
The list of keyframes for a keyframe animation effect is
loosely sorted by offset which means that for each
keyframe in the list that has a keyframe offset that is
not null, the offset is greater than or equal to the offset of the
previous keyframe in the list with a keyframe offset that
is not null, if any.
The behavior when keyframes overlap or have unsupported values
is defined in .
Each keyframe also has a timing function associated with it
that is applied to the period of time between the keyframe on which it
is specified and the next keyframe in the list.
The timing function specified on the last keyframe in the
list is never applied.
Each keyframe animation effect has an associated composition
operation that specifies how it is combined with other animation
effects in the animation stack.
Furthermore, each keyframe may also have an associated
composition operation that is applied to all values specified in
that keyframe.
If no composition operation is specified for a keyframe,
the composition operation specified for the keyframe
animation effect is used.
Spacing keyframes
It is often useful to be able to provide a series of property values
without having calculate the keyframe offset of each value in
time but instead to rely on some automatic spacing.
For example, rather than typing:
elem.animate([ { color: 'blue', offset: 0 },
{ color: 'green', offset: 1/3 },
{ color: 'red', offset: 2/3 },
{ color: 'yellow', offset: 1 } ], 2);
It should be possible to type the following and allow the user agent
to calculate the offset of each
keyframe:
elem.animate([ { color: 'blue' },
{ color: 'green' },
{ color: 'red' },
{ color: 'yellow' } ], 2);
Web Animations provides spacing modes for this purpose. The default
spacing mode for keyframe animation effects is
“distribute” which
produces the result described above.
The other spacing mode, “paced”, is useful when
it is desirable to maintain an even rate of change such as for motion path animation.
For example, consider the following animation:
elem.animate([ { left: '0px' },
{ left: '-20px' },
{ left: '100px' },
{ left: '50px' } ], 1);
The resulting value of the left
property is illustrated below:
The animated value of the left property over time when applying the
distribute spacing
mode.
The values are evenly spaced in time but the rate of change differs
for each segment as indicated the varying slope of the graph.
We can use the paced
spacing mode as follows:
elem.animate(
new KeyframeEffect([ { left: '0px' },
{ left: '-20px' },
{ left: '100px' },
{ left: '50px' } ], { spacing: "paced" }), 1);
The result is illustrated below:
The animated value of the left property over time when applying the
paced spacing mode.
The absolute value of the slope is graph is equal for all segments
of the animation indicating a constant rate of change.
It is also possible to combine fixed keyframe offsets with
spacing modes as follows:
elem.animate(
new KeyframeEffect([ { left: '0px' },
{ left: '-20px' },
{ left: '100px', offset: 0.5 },
{ left: '50px' } ], { spacing: "paced" }), 1);
The result is illustrated below:
The animated value of the left property over time when applying the
paced spacing mode and
a fixed keyframe offset that
puts the 100px value at 0.5.
The slope of the graph is equal for the first two segments but
changes for the last segment in order to accommodate the fixed
offset.
Before calculating animation values from a keyframe animation
effect, an absolute value must be computed for the keyframe
offset of each keyframe with a null offset.
The values computed depend on the keyframe spacing mode
specified for the keyframe animation effect.
The keyframe spacing modes are:
- distribute
-
Indicates that keyframes with a null keyframe offset
null are positioned so that the difference between subsequent
keyframe offsets are equal.
- paced
-
Indicates that keyframes with a null keyframe offset
null are positioned so that the distance between subsequent
values of a specified paced property are equal.
The distance is calculated using the distance computation
procedure defined by the animation behavior associated
with the paced property.
Applying spacing to keyframes
We define a generic procedure for evenly distributing
a keyframe, keyframe, between two reference
keyframes, start and end, whose keyframe
offsets are not null, as follows:
- Let offsetk be the keyframe
offset of a keyframe k.
- Let n be the number of keyframes between and
including start and end minus 1.
- Let index refer to the position of
keyframe in the sequence of keyframes between
start and end such that the first keyframe
after start has an index of 1.
- Set the keyframe offset of keyframe to
offsetstart +
(offsetend −
offsetstart)
× index / n.
The computed keyframe offset values of each keyframe
with a null keyframe offset are determined using the following
procedure.
- Let keyframes refer to the list of keyframes
associated with the keyframe animation effect.
- If keyframes contains more than one
keyframe and the keyframe offset of
the first keyframe in keyframes is null,
set the keyframe offset of
the first keyframe to 0.
- If the keyframe offset of the last keyframe in
distributed keyframes is null, set its
keyframe offset to 1.
- For each pair of keyframes A and B
where:
calculate the keyframe offset of
each keyframe between A and B
depending on the keyframe spacing mode as follows:
- If the spacing mode
is paced,
-
- Define a keyframe as paceable if it
contains a value for the paced property.
- Let paced A be the first keyframe in the
range [A, B] that is
paceable, if any.
- Let paced B be the last keyframe in the
range [A, B] that is
paceable, if any.
- If there is no paced A or paced
B let both refer to B.
Note that in this case, the spacing
behavior degenerates to distribute
spacing.
- For each keyframe in the range
(A, paced A] and
[paced B, B),
apply the procedure for evenly distributing
a keyframe using A and B as
the start and end keyframes
respectively.
Yes, this is correct.
We want, index and n in that
procedure to reflect all the keyframes
between A and B, not just the
keyframes between, for example, A and
spaced A.
- For each keyframe in the range
(paced A, paced B) that is
paceable:
- Let
distk
represent the cumulative distance to a keyframe
k from paced A
as calculated by applying the distance
computation defined by the animation
behavior of the paced property to the
values of the paced property on each pair of
successive paceable keyframes in the range
[paced A, k].
- Set the offset of k to
offsetpaced
A
+
(offsetpaced
B
−
offsetpaced
A)
×
distk
/
distpaced
B
- For each keyframe in the range (paced A,
paced B) that still has
a null keyframe offset (because it is not
paceable), apply the procedure
for evenly distributing a keyframe using
the nearest keyframe before and after the
keyframe in question in keyframes that has
a keyframe offset that is not null, as the
start and end keyframes
respectively.
- Otherwise,
-
Apply the procedure for evenly distributing
a keyframe to each keyframe in the range (A,
B) using A and B as the
start and end keyframes respectively.
Note that although the above procedure defines computing keyframe
offsets in terms of overwriting null values, user agents that
implement the programming
interface are required to maintain the original null values as
well as calculating the computed offsets.
This is because the getFrames method of the
Timing interface returns keyframe offsets both before
and after applying spacing.
The above algorithm is quite complex.
It attempts to cover all possible combinations of input where
keyframe offsets and or paced property values may be missing.
Furthermore, it attempts to do this in a way that degenerates
consistently and also allows the author to combine fixed offsets
with either pacing or distribute spacing.
We await implementation experience to determine if the complexity
is justified.
The unaccumulated animation value of a keyframe animation effect
The unaccumulated animation value of a single property
referenced by a keyframe animation effect as one of its
target properties, for a given time
fraction and underlying value is calculated as follows.
- Let target property be the property for which the
unaccumulated animation value is to be calculated.
- If animation behavior of the target property is
not animatable abort this procedure since the effect cannot
be applied.
- Let time fraction be the time fraction for which
the unaccumulated animation value is to be calculated.
- Let underlying value be the current underlying
value for target property.
- Define the neutral value for composition as a value
which, when combined with an underlying value using the add composition
operation, produces the underlying value.
- Let property-specific keyframes be a copy of the list
of keyframes specified on the effect.
- Remove any keyframes from property-specific
keyframes that do not have a property value for
target property.
- If property-specific keyframes is empty, return
underlying value.
- If there is no keyframe with a keyframe offset of
0, create a new keyframe with a keyframe offset of
0, a property value set to the neutral value for
composition, and a composition operation of add, and add it to the
beginning of property-specific keyframes.
- Similarly, if there is no keyframe with a keyframe
offset of 1,
create a new keyframe with a keyframe offset of 1,
a property value set to the neutral value for composition,
and a composition operation of add, and append it to the
end of property-specific keyframes.
- Iterate over each keyframe in property-specific
keyframes and for each keyframe, if:
perform the following steps:
- Let value to add be the property value of
target property specified on keyframe.
- Replace the property value of target property on
keyframe with the sum of
underlying value (Va) and
value to add (Vb)
using the addition
procedure defined by target property's
animation behavior.
- If time fraction < 0 and there is more
than one keyframe in property-specific
keyframes with a keyframe offset of
0, return the property value for target property of the
first keyframe in property-specific
keyframes.
- If time fraction ≥ 1 and there is more than one
keyframe in property-specific keyframes with
a keyframe offset of 1, return the property value for
target property of the last keyframe in
property-specific keyframes.
- Otherwise, let start keyframe be the last
keyframe in
property-specific keyframes whose keyframe
offset is less than or equal to time fraction and
less than 1.
If there is no such keyframe (because, for example, the
time fraction is negative), let start keyframe
be the last keyframe whose keyframe offset is 0.
Does the condition beginning “If there is no such
keyframe…” ever happen?
There is always at least one keyframe at zero because we
synthesize one earlier if there is not. And if time
fraction is less than zero then we deal with it above, so
there should always be a keyframe with offset ≤ time
fraction by this point right?.
- Let end keyframe be the next keyframe in
property-specific keyframes after start
keyframe.
- Let start offset be the keyframe offset of
start keyframe.
- Let end offset be the keyframe offset of
end keyframe.
-
Let interval distance be the result of evaluating
(time fraction - start offset) /
(end offset - start offset)
-
Return the result of interpolating between start keyframe
and end keyframe by using the interpolation procedure defined
by the animation behavior of the target property
using interval distance as the interpolation parameter
p and the property values of target
property specified on start keyframe and end
keyframe as Vstart and
Vend repsectively.
Note that this procedure assumes the following about the list of
keyframes specified on the effect:
- Each keyframe has a specified keyframe offset in
the range [0, 1].
- The list of keyframes is sorted in ascending order by
keyframe offset.
- Each specified property value is a valid and supported value.
- For a given property, there is a most one specified property
value on each keyframe.
It is the responsibility of the user of the model (for example,
a declarative markup or programming interface) to ensure these
conditions are met.
For example, for the programming
interface defined by this specification, these conditions are
met by applying the normalization defined in and
resolving null keyframe offsets by
applying spacing behavior.
Note that this procedure permits overlapping keyframes.
The behavior is that at the point of overlap the output value jumps to
the value of the last defined keyframe at that offset.
For overlapping frames at 0 or 1, the output value for time fractions less than 0 or greater than
or equal to 1 is the value of the first keyframe or the last
keyframe in keyframes respectively.
In the presence of certain timing functions, the input time
fraction to an animation effect is not limited to the range [0, 1].
Currently, however, keyframe offsets are limited to the
range [0, 1] and property values are simply extrapolated for input
time fractions outside this range.
We have considered removing this restriction since some cases exist
where it is useful to be able to specify non-linear
changes in property values at time fractions outside the range
[0, 1].
One example is an animation that interpolates from green to yellow
but has an overshoot timing function that makes it temporarily
interpolate ‘beyond’ yellow to red before settling back
to yellow.
While this effect could be achieved by modification of the keyframes
and timing function, this approach seems to break the model's
separation of timing concerns from animation effects.
It is not clear how this effect should be achieved but we note that
allowing keyframe offsets outside [0, 1] may make the currently
specified behavior where keyframes at offset 0 and 1 are synthesized
as necessary, inconsistent.
See section
4 (Keyframe offsets outside [0, 1]) of minuted discussion from Tokyo
2013 F2F.
Motion path animation effects
A motion path animation effect is an animation effect
that produces animation values for the transform target
property of an animation target such that it follows
a geometric curve commonly referred to as a “motion path”.
The motion path of a motion path animation effect is
defined by an SVG Path, as specified by SVG [[!SVG2]].
A motion path consists of a list of path commands (see path data
[[!SVG2]]).
Amongst the different types of path commands, we define
orientation path commands as
moveto
commands and bearing
commands.
All types of path commands that are not orientation
path commands are referred to as drawing path commands.
The automatic rotation flag of a motion path animation
effect, if set, specifies that the unaccumulated animation
value generated by the motion path animation effect produces
a rotation that matches the directional tangent vector of the
motion path.
The rotation angle parameter of a motion path animation
effect specifies a constant rotation that applies to the target
transform in addition to any rotation generated by setting the
automatic rotation flag.
Each motion path animation effect has an associated
composition operation that specifies whether the unaccumulated
animation values generated by the effect replace the underlying value
or add to it.
Distance along a path
The procedure used for calculating the length of a path or a section
of a path is provided by the definition of distance
along a path in SVG [[!SVG2]].
Spacing motion paths
The following properties control the rate of progress of a motion
path animation effect:
- spacing mode
-
Specifies the strategy used for determining the offset of each
spacing point or path command when not specified by
a point offset.
The possible spacing modes are identical to those defined for
keyframe animation effects (see ).
Note that a distribute has no
effect if point offsets are specified.
This is because spacing between point offsets uses
paced spacing mode.
- spacing points
-
An optional sequence of real numbers in the range [0.0, 1.0] that
correspond to fractions of the total path length.
The animation effect produces animation values such that the
animation target moves backwards and forwards along the
motion path following the sequence indicated by these
points.
Furthermore, the point on the motion path indicated by each
such number forms a handle that may be associated with a point
offset or otherwise positioned by the motion path spacing
mode.
- point offsets
-
An optional ordered sequence of real numbers in the range [0.0,
1.0] that specifies the time fraction when the
corresponding spacing point, or, if spacing points
are not provided, path command, should be visited.
If specified, the first value in the list must be 0.0 and the
last value must be 1.0.
There must be as many items in the sequence as in the sequence of
spacing points, if provided.
If a sequence of spacing points is not provided,
the number of items in point offsets must equal the number
of drawing path commands in the motion path plus
one.
Need a diagram here showing how the different combinations work.
Applying spacing to motion paths
The end result of applying spacing is a sequence of effective
spacing points and a sequence of effective point offsets
calculated using the following procedure:
The sequence of effective spacing points is determined by
following the steps associated with the first matching condition
from below:
- If spacing points is specified,
-
Let effective spacing points refer to spacing
points.
- If the spacing mode
is paced and point
offsets is not specified,
-
Let effective spacing points be a sequence consisting
of the values [0, 1].
- Otherwise,
-
Perform the following steps:
- Let effective spacing points be a sequence
consisting of the single element 0.
- For each drawing path command in path
commands, append to effective spacing points
a number equal to the distance along a path up to
the point at the end of the given path command,
divided by the total path length.
Having determined the effective spacing points, the sequence
of effective point offsets is determined by following the
steps associated with the first matching condition from below:
- If point offsets is specified,
- Let effective point offsets refer to point
offsets.
- If the spacing mode
is distribute,
-
Perform the following steps:
- Let effective point offsets be a sequence of
equal length to effective spacing points.
- Let n be the number of elements in
effective point offsets minus one.
- Let k represent an index in the range [0,
n].
- Set the value of each point in effective point
offsets so that the point at index k
is equal to k / n.
- Otherwise,
-
Perform the following steps:
- Let effective point offsets be a sequence of
equal length to effective spacing points.
- Let n be the number of elements in
effective point offsets minus one.
- Let k represent an index in the range [0,
n].
- Let point(k)
represent the value of effective spacing points
at index k.
- Set the value of each point in effective point
offsets so that the value at index k is
defined by the following formula:
- For k = 0, offset = 0
- For k = 1..n,
offset =
[ \sum_{i=1}^k ( point(i)-point(i-1) ) ]
/
[ \sum_{i=1}^n ( point(i)-point(i-1) ) ]
Determining the path fraction
The path fraction for a given time fraction,
progress, is determined using the following procedure:
- If effective point offsets is empty, let path
fraction equal time fraction and abort these steps.
- If effective point offsets has only one item, let path
fraction equal the value of the one item in effective
point offsets and abort these steps.
- If progress ≥ 1, let the path fraction equal
the value of the last item in effective point
offsets and abort these steps.
- If progress < 0, let the path fraction equal
the value of the first item in effective point
offsets and abort these steps.
- Let start index and end index represent
the zero-based indices of the last pair of successive
values in effective point offsets such that start
offset ≤ progress ≤ end offset.
- Let interval fraction be the ratio of the difference
between progress and the offset at start
index, and the difference between the offset at end
offset and the offset at start offset.
- Let segment start and segment end be the
values in effective spacing points at the indicies
start index and end index respectively.
- Let the path fraction be the result of evaluating the
following formula:
interval fraction * (segment end
- segment start) + segment start.
The unaccumulated animation value of a motion path animation effect
The unaccumulated animation value of a motion path animation
effect for a given time fraction and underlying
value is given by the following process:
-
Let distance be the path fraction for the given
time fraction.
-
Let displacement be the point located
distance along the motion path using the
definition for distance along a path.
If distance indicates a point on the path that is
coincidental with one or more orientation path
commands, displacement is the point
after all orientation path commands (this will
be the start of the next drawing path command if
there is one).
-
Let the translation component be the translation
transform required to transform the point at the start of
motion path to displacement.
- Calculate the rotation component according to the
first match condition from the following:
- If the automatic rotation flag is set,
-
the rotation component is a transform representing
the rotation angle.
- Otherwise,
-
the rotation component is a transform representing
the sum of:
-
the angle of the tangent vector at
displacement, and
-
the rotation angle.
When calculating the angle of the tangent vector, if there are
no drawing path commands in the motion path, the
the angle should be taken to be zero.
The original text for this section contained the following
qualifications but I'm not sure how meaningful they are:
-
For continuous path commands (all elements except
moveto), the angle of the tangent vector for the purpose of
these calculations is defined to be an integer multiple of
2π different from the value given by standard
mathematical formulae for tangents to curves in
2 dimensional space.
-
For moveto path commands, which are discontinuous, the
angle of the tangent vector for the purpose of these
calculations is always an integer multiple of 2π.
-
The initial value of the angle of the tangent vector is
computed using the first element of the curve, and is always
in the range [0, 2π).
-
Single continuous path commands must never produce tangent
vector angles that are discontinuous over their defined
region. This implies that a single unique solution is
available for all points on continuous path commands.
-
When computing angles after discontinuous or non-smooth
jumps, multiple possible solutions may be available. These
solutions will differ by integer multiples of 2π. In
such cases the solution that lies closest to the previous
tangent angle is used.
-
Let the transform value be the result of
by constructing a transform list consisting of the
translation component followed by the rotation
component.
What's the value in keeping these separate?
Shouldn't we collapse them?
-
The unaccumulated animation value of the motion path
animation effect depends on the value of its composition
operation as follows,
- If the composition operation of this motion path
animation effect is replace,
-
the unaccumulated animation value of the effect is
transform value.
- Otherwise,
-
the unaccumulated animation value of the effect is the
result of adding transform to the underlying
value using the procedure
for addition defined for by the animation behavior
of the underlying value.
Need to define the when accumulating we collapse the transforms so
that we don't end up with a list that grows in an unbounded fashion
over time.
Custom effects
A custom effect is an author-defined programming callback
that is passed timing information whenever a sample is performed.
Execution order of custom effects
Since custom effects, unlike animation effects, are not limited to
a single target property, the steps for assessing their
order of execution differs from animation effects.
Custom effects are executed after all
animation effects have completed and
applied their result to their targets (see ).
Need to define this more precisely.
Are styles flushed?
Presumably they are.
Can we suspend reflow for the duration of executing the script-based
animation effects and just do it once afterwards?
Within the set of custom effects, the
order of execution is the same as that defined for animation effects in .
Items sorted earlier are executed before those sorted later.
Timing events
Possibly move this section into
.
The current event model has two undesirable consequences:
-
There are two different modes in which events are dispatched:
seeked mode and regular mode.
Some applications will need to provide different handling based on
the mode which complicates handling.
Other applications will simply assume seeked mode behavior since
the mode can change based on parameters outside the application's
control (such as being switched to a background tab causing the
refresh rate to drop and the maximum event threshold to be
exceeded).
-
Uneased timing can cause events to be reordered with respect
to how they are visually percieved and can also cause events
to be delivered with timestamps in the future.
One alternative under consideration is as follows:
-
Primitive onstart / onend events that fire only when an
animation first starts playing and last stops playing.
-
An onchange event that fires when the play state (e.g. current
iteration, fill state, etc.) of an Animation changes, and provides
a summary only of ther changes since the last sample.
No more than one event is generated per animation per sample.
-
The list of actual changes associated with a change event would be
lazily generated since this could be costly to generate for large
sample intervals.
See sections
8 and 14 of minuted discussion from Tokyo 2013 F2F.
Another possibility is that rather that switching to seeked event
dispatch when there are many events to dispatch due to delays between
samples, to instead ignore the delay (as is required for SVG).
This would make seeked event dispatch predictable.
This approach, however, does not address the issues regarding uneased
timing.
As timed items play they report changes to
their status through timing events.
Timing events are a property of the Web
Animations timing model.
As a result they are dispatched even for animations that do not have an associated
animation effect, for animations whose
animation target is not rendered because it or a parent element
has display property of none, and for timed
items that perform no animation such as timing groups.
Relationship to CSS and SVG events
CSS defines AnimationEvents and
TransitionEvents and SVG defines TimeEvents.
The proposal here is to dispatch TimingEvents in parallel to
these events.
A key difference is that the target of a TimingEvent is a
TimedItem and not content.
This model leaves firing of events at content up to the declarative
mapping onto the model (e.g. CSS or SVG).
This approach makes the Web Animations model more self-contained
whilst permitting different mappings for different markup.
For example, CSS fires events at the animation target element whilst
SVG fires events at the element that generated the animation.
Types of timing events
- timingstart
-
Occurs at the moment when a timed item enters its active
interval (from either direction).
Note that if the parent timing group starts a new
iteration, this is treated as if this element momentarily exited
its active interval (producing a new timingend
event), and entered it again (producing a new timingstart
event).
- Bubbles: yes
- Cancelable: no
- Context Info: localTime, documentTime, iterationIndex,
seeked
- timingiteration
-
Occurs at the moment when a repeating
timed item's current iteration changes value
excluding changes to and from null.
Note that if the parent timing group starts a new
iteration, this is treated as if this element momentarily exited
its active interval (causing the current iteration
to become null), and entered it again (producing
a new value for current iteration) and hence producing no
timingiteration event since the only changes to current
iteration are to and from null.
- Bubbles: yes
- Cancelable: no
- Context Info: localTime, documentTime, iterationIndex,
seeked
- timingend
-
Occurs at the moment when a timed item leaves its active
interval (from either direction).
- Bubbles: yes
- Cancelable: no
- Context Info: localTime, documentTime, iterationIndex,
seeked
- timingcancel
-
Occurs when a timed item loses its association with
a player.
- Bubbles: yes
- Cancelable: no
- Context Info: None
Can we rename these to just start, iteration,
end, and cancel?
They are only fired at timed items, never
DOM nodes, so they won't clash with other events.
Is that enough or do the names need to be globally unique?
Uneased timing
The uneased timing of a timed item refers to
performing any of the calculations defined for the timed item
with the following exceptions:
For example, the uneased inherited time of a timed
item is calculated using the regular definition of inherited
time after applying the two modifications to the timing of the
item and its ancestors noted above.
Normally the time value used as input to a child timed item
of a timing group is the group's transformed time.
However, since uneased timing does not apply timing functions, we refer to uneased
child time which is equivalent to both uneased transformed
time and uneased directed time.
Inverse timing calculations
For times calculated using uneased timing it is possible to
perform the reverse operation to, for example, convert times from
a child timed item to that of its its parent timing
group or timeline.
Calculating the uneased local time from uneased child
time of a given timed item requires recording the
iteration index that corresponds to the uneased child time and
is calculated as follows.
- Let item be the timed item for which the
uneased local time is to be calculated.
- Let child time be the uneased child time to be
converted.
- Let iteration index be the value of current
iteration corresponding to child time.
- Calculate the current direction of item
using the procedure defined in substituting iteration index
for the current iteration.
-
Let the uneased iteration time be the result
corresponding to the first matching condition from below.
- If the current direction is forwards,
-
child time
- Otherwise,
-
iteration duration - child time
-
Let the uneased scaled active time be the result
corresponding to the first matching condition from below.
- If iteration duration is zero,
-
zero
- If uneased iteration time equals iteration
duration,
-
repeated duration × start
offset
- Otherwise,
-
iteration index × iteration
duration + uneased iteration time
-
Let the uneased active time be the result corresponding
to the first matching condition from below.
- If the playback rate
is zero,
-
positive infinity unless scaled active time is zero,
in which case the active time is zero
- If the playback rate
is positive,
-
(uneased scaled active time - start
offset) / playback
rate
- Otherwise,
-
(uneased scaled active time - start
offset) / playback
rate + active duration
- Return
uneased active time + start
delay.
Note that the above procedure is only defined when the uneased
child time is defined, that is, not null.
The uneased inherited time from uneased local
time is simply the sum of the uneased local time
and the timed item's start time.
The timeline time from the current time of
a player is calculated as follows.
timeline time =
(current time + time lag) /
playback rate +
start time
If the player's playback rate is
zero, the timeline time is undefined.
The handling of an undefined value depends on the context in which it
is used.
Typically, a current time value for the timeline is
available and this is used in place of the undefined value.
Provided that the current iteration values used when
calculating the uneased local time are recorded, it is
possible, by applying the above definitions in succession, to
calculate the time value of a timeline corresponding to
the uneased local time of a timed item associated with that
timeline.
Propagation path
The propagation
path for a timing event generated by item,
is simply item itself.
Note that unlike AnimationEvents and
TransitionEvents in CSS, and TimeEvents in
SVG, all of which target an Element; the target of a timing
event is a timed item.
Event dispatch
Events are queued when either of the following occurs:
In the former case—when a timeline is sampled—since Web Animations put no
requirements on the time between successive samples, it is often the
case that the moment when a change in state that should produce an
event is scheduled to occur does not line up with a sample.
As such, except for the specific circumstances mentioned in following
sections, the events that should be queued when sampling
a timeline includes all events scheduled to occur in the
interval since the previous sample time up to and including the
current timeline time.
Note that when a player is first sampled, it will employ seeked event
dispatch as described in
after which point the previous sample time for that player
will be resolved.
As a result, there is never an occasion where the previous sample time
is used and yet is undefined.
For the latter case—when a player is seeked—the behavior is defined in .
Make sure we update the previous sample time for a seek/etc.
Note that provides non-normative algorithms that
incorporate the behavior defined in this section as well as .
Event dispatch and extended delays
If, whilst sampling a timeline, more than 30 events
are queued, the user agent MAY employ seeked event
dispatch for all timed items associated with the
timeline.
30 is somewhat arbitrary.
Need feedback both from implementations (on the most constrained
device, when does this start being burdensome?) and authoring (what
is the minimum guarantee necessary to cover most regular content?)
The SVG bindings may add additional requirements here so that when
a protracted delay may make resolving syncbase dependencies in the
interim period difficult to achieve without adversely impacting
performance, a seek is performed.
Script interface
The Timeline interface
Timelines, including the document
timeline are represented in the Web Animations API by the
Timeline interface.
- readonly attribute double? currentTime
-
Returns the time value for this timeline or
null if this timeline is not started.
For a document timeline this will never be negative and
represents the number of seconds since the document with which
this timeline is associated was ready to fire its load
event.
- Player play()
-
Creates a new Player object
associated with this timeline that is scheduled to start
at currentTime.
The timeline attribute of the newly-created Player object will be set to this
object.
Similarly, the startTime attribute will be set to the
value of this object's currentTime attribute at the
moment the method was called, or, if currentTime is
null, zero.
The setting of the source attribute is described
below under the description of the source parameter.
The currentTime attribute of the Player object is a calculated value described in .
The playbackRate and paused attributes
take on their default values as described in the definitions of
the playback rate and
paused state properties of player objects.
- optional TimedItem? source = null
-
The source content to assign to the newly-created Player object.
The source
attribute of the created Player is set by following the procedure
defined for updating that attribute.
As a result, if source is already associated with
a player, it will be disassociated first before
being associated with the new Player object.
We will likely change this interface to the following format:
Promise play(optional TimedItem? source = null);
Player playNow(optional TimedItem? source = null);
Under this arrangement play would begin at the next
possible moment whilst attempting to ensure that the animation
begins from the first frame.
This allows implementations to make adjustments for vsync or
overhead in triggering the animation in another process.
The play callback passes the created Player as the argument to the
Promise's fulfill callback.
playNow matches the existing definition of the
function and causes the start time of the player to be set to
this timeline's currentTime even though this may
cause the first part of the animation to be dropped.
- sequence<Player> getCurrentPlayers()
-
Returns the set of Player objects
associated with this timeline that have associated
source content which is current.
The returned list is sorted in increasing order by player
sequence number.
- double? toTimelineTime (double otherTime, Timeline other)
-
Returns the time value, otherTime, from another
Timeline also tied to the
global clock, other, converted to a time
value relative to this timeline's zero time.
Returns null if:
Note that unlike currentTime, this method may return
a negative time value if otherTime occurred prior
to this timeline's zero time.
Furthermore, negative values for otherTime are also
allowed.
If this timeline records the time value of the global
clock at its zero time as global clock
offset, and so does other as other global
clock offset, then the result of this method is simply:
other global clock offset + otherTime
- global clock offset
Exceptions:
- DOMException of type
InvalidNodeTypeError
-
Raised if other is a timeline that is not tied to the
global clock.
The reason for choosing InvalidNodeTypeError here
is that DOM4 describes it as meaning, "The supplied node is
incorrect or has an incorrect ancestor for this operation."
In this case the error is because other does not have
the global clock as an ancestor so it seems
appropriate.
- double? toTimelineTime (Event event)
-
Returns the number of seconds between when event was
fired and this timeline's zero time.
Since the timeStamp attribute of the
Event interface specified in [[DOM-LEVEL-3-EVENTS]]
is not guaranteed to be monotonically increasing, implementations
SHOULD record alongside each event the time value of the
global clock when the event is dispatched so that it can be
converted to an accurate time value here.
Unlike currentTime, this method may return a negative
time value if the event was fired prior to this
timeline's zero time.
Returns null if this timeline is not
started.
This might be deferred to a later version.
The Player interface
Players are represented in the Web Animations
API by the Player interface.
- attribute TimedItem? source
-
The source content associated with this player.
A player can only be associated with at most one timed
item, and likewise, a timed item can only be
associated with at most
one player.
In order to maintain these invariants, on setting this value, the
following procedure is performed:
- Let old value be the current value of the
source attribute.
- Let new value be the value to set.
- If new value is the same object as old
value, return.
- If old value is not
null,
disassociate old value from this player.
- If new value is not
null,
perform the steps associated with the first matching condition
of the following:
- If new value has no parent group and is
associated with a player,
- disassociate new value from its player.
- If new value has a parent group,
- remove new value from its parent group by
calling
new value.remove().
- Otherwise,
- do nothing.
- Associate new value with this player.
- Set the
source attribute to new
value.
- readonly attribute Timeline timeline
-
The timeline associated with this player.
- attribute double startTime
-
The start time of this player.
On setting, the hold time must be reset to
null so that when the time lag is recalculated
(see )
the hold time will be updated accordingly.
- attribute double currentTime
-
The effective current time of this player.
Setting this attribute follows the procedure defined in .
- readonly attribute double timeLag
-
The time lag of this player which represents the number of
seconds the
currentTime has been delayed due to pausing
and seeking.
Negative values indicate the player has been advanced ahead of its
scheduled time by seeking.
- attribute double playbackRate
-
The playback rate of this
player.
Setting this attribute follows the procedure defined in .
- readonly attribute boolean paused
-
The paused state of this player.
- readonly attribute boolean finished
-
Returns true if this player has reached or passed the end of
its source content in its current playback direction.
This corresponds to when the player is limited.
- void cancel()
-
Set
source to null and clears all effects associated
with the previous source content.
We need to make sure, for example, that any custom effects get
called with a null sample time so they can remove their effects.
This applies to manually setting source to null as
well so we should define this behavior there.
- void finish()
-
Seeks the player to the end of the source content in the
current direction as follows:
- If player playback rate < zero,
-
Seek the player so its
current time is zero.
- If player playback rate equals zero,
-
Do nothing.
- If player playback rate > zero,
-
Seek the player so its
current time is equal to the end time of the
source content or zero if there is no source
content associated with this player..
Exceptions:
- DOMException of type
InvalidStateError
-
Raised if the end time of this player's source
content is infinity and the player playback rate is
> zero.
- void play()
-
Unpauses the player and rewinds if it has finished playing using
the following procedure:
- Set the paused state of the player to false using the
procedure defined in .
- If source content is associated with the player,
adjust the current time of
the player as follows:
- If player playback rate > 0; and
either current time < zero or
current time ≥ source
content's end time,
- Seek to time zero.
- If player playback rate < 0; and
either current time ≤ zero or
current time > source
content's end time,
- Seek to the source content's end
time.
- Otherwise,
- Do nothing.
- void pause()
-
Set the paused state of this player to true using the
procedure defined in .
- void reverse()
-
Inverts the playback rate of
this player and seeks to the start of the source media if it has
finished playing in the reversed direction using the following
procedure.
- If the player playback rate is zero, abort these steps.
- If source content is associated with the player,
adjust the current time of
the player as follows:
- If player playback rate > zero and
effective current time > source
content's end time,
- Seek to the source content's end time.
- If player playback rate < zero and
effective current time < zero,
- Seek to time zero.
- Otherwise,
- Do nothing.
- Set the player playback rate to
-player
playback rate following the steps in .
- Set the paused state of the player to false.
Is this unpausing behavior correct?
The TimedItem interface
Timed items are represented in the Web
Animations API by the TimedItem interface.
- // Playback state
- readonly attribute double? localTime
-
The local time of this timed item.
localTime will be null if this timed
item is not associated with a player or if it has
a parent timing group that is not in effect.
- readonly attribute unsigned long? currentIteration
-
The current iteration index beginning with zero for the first
iteration.
- // Specified timing
- readonly attribute Timing specified
-
Returns the input timing properties for this timed item.
Should we make this writeable? Then you could do:
animA.specified = animB.specified;
Doing so would probably also involve defining
Timing.clone and a constructor for Timing.
Representing these parameters has been a particularly
contentious topic.
The current arrangement:
- requires defining both a Timing interface and
a TimingInput dictionary type which increases the API
surface area somewhat
- means that setting the value occurs at a different place
(
anim.specified.duration) to reading
the value (typically, anim.duration)
- opens up questions about whether Timing objects
should be share-able or not
- uses a union of a string and a double to represent
a duration which opens up questions about whether strings
such as
"3s" should be allowed (and allowing
them makes walking the tree more complex).
However, it separates "specified" timing from "computed" timing
which some consider advantageous.
The only situation where calculated values and input values
differ is for duration.
One alternative that has been proposed is to introduce
a Duration interface as follows:
interface TimedItem : EventTarget {
// Timing
attribute double delay;
attribute FillMode fill;
attribute Duration duration;
attribute double playbackRate;
// ...
// Scheduled time
readonly attribute double startTime;
readonly attribute unrestricted double endTime;
};
interface Duration {
double sec;
DOMString string;
}
Usage is as follows:
var specifiedDur = anim.duration.string; // "auto"
var calculatedDur = anim.duration.sec; // 5
// Update duration to 3s
anim.duration.sec = 3;
// anim.duration.string -> "3s"
// Update duration to 3s (alt.)
anim.duration.string = "3s";
// anim.duration.sec -> 3
// Reset to auto
anim.duration.string = "auto";
// anim.duration.sec -> 5
Your feedback is most welcome at public-fx@w3.org, subject
[web-animations] ….
- // Calculated timing
- readonly attribute double startTime
-
The start time of this timed item in seconds.
This is the time at which the parent timing group, if any,
has scheduled this child to run within its transformed time space, that is, the timed item's
inherited time space.
The start of the active interval is based on the sum of
the start time and
start delay.
- readonly attribute unrestricted double duration
-
The iteration duration of this timed item.
Unlike the duration attribute of
the Timing interface or TimingInput dictionary,
this attribute returns the calculated value of the iteration
duration.
If specified.duration is the
string auto or any unsupported value, this attribute
will return the current calculated value of the intrinsic
iteration duration.
This value may be changed by setting the
duration attribute of the
specified member of this interface.
- readonly attribute unrestricted double activeDuration
-
The active duration of this timed item.
- readonly attribute unrestricted double endTime
-
The end time of the timed item expressed in
seconds in inherited time space.
This corresponds to the end of the timed item's active
interval plus any end delay.
- // Timing hierarchy
- readonly attribute TimingGroup? parent
-
The parent timing group of this timed item or
null if this timed item does not have
a parent timing group.
Should this be parentGroup?
- readonly attribute TimedItem? previousSibling
-
The previous sibling of this timed item.
- readonly attribute TimedItem? nextSibling
-
The next sibling of this timed item.
- void before (TimedItem... items)
-
Inserts items before this timed item.
- If there is no parent timing group, terminate these
steps.
- If any of the timed items in items is an
inclusive ancestor of this timed item
throw a
HierarchyRequestError exception and
terminate these steps.
- Insert items before
this timed item.
Note that this definition precludes the following usage since
item is an inclusive ancestor of itself:
item.before(item); // throws HierarchyRequestError
- void after (TimedItem... items)
-
Inserts items after this timed item.
- If there is no parent timing group, terminate these
steps.
- If any of the timed items in items is an
inclusive ancestor of this timed item
throw a
HierarchyRequestError exception and
terminate these steps.
- Let reference child be the next sibling of
this timed item not in items.
- Insert items before
reference child.
- void replace (TimedItem... items)
-
Replaces this TimedItem with the passed in
items.
- If there is no parent timing group, terminate these
steps.
- If any of the timed items in items is an
inclusive ancestor of the parent timing group
throw a
HierarchyRequestError exception and
terminate these steps.
- Let reference child be the next sibling of
this timed item not in items.
- Remove this timed
item from its parent timing group.
- Insert items before
reference child.
- void remove ()
-
Removes this timed
item from its parent timing group or player.
- // Associated player
- readonly attribute Player? player
-
The player with which this timed item is associated, if any.
This object can be used to perform play control such as pausing or
rewinding on this timed item and all other timed items
in the same hierarchy.
This will be null if this timed
item is not associated with a player.
- // Event callbacks
- attribute EventHandler onstart
-
The event handler for the timingstart event.
- attribute EventHandler oniteration
-
The event handler for the timingiteration event.
- attribute EventHandler onend
-
The event handler for the timingend event.
- attribute EventHandler oncancel
-
The event handler for the timingcancel event.
Note that the EventHandler
callback interface type is defined in [[!HTML5]].
The Timing interface
Timing parameters for a TimedItem are collected together under
the Timing type.
- attribute double delay
-
The start delay which represents the number of seconds from
a timed item's start time to the
start of the active interval.
Now that we have endDelay, should we change this back
to startDelay?
- attribute double endDelay
-
The end delay which represents the number of seconds from
the end of a timed item's active interval until the
start time of any timed item that may follow, for
example, in a sequence timing group.
- attribute FillMode fill
-
The fill mode as specified by one of the FillMode
enumeration values.
When performing timing calculations the special value auto is expanded
to one of the fill modes recognized by the timing model as
follows,
-
If the timed item to which the fill mode is being is
applied is an animation,
-
Use none as the fill
mode.
- Otherwise,
-
Use both as the fill
mode.
- attribute double iterationStart
-
The timed item's iteration start property.
A finite real number greater than or equal to zero representing
the number of iterations into the timed item at which to begin.
For example, a value of 0.5 would cause the timed item to begin
half-way through the first iteration.
Values less than zero are clamped to zero for the purpose of
timing model calculations.
Note that the value of iterations is effectively
added to the iterationStart such that
a timed item with an iterationStart of
‘0.5’ and iterations of
‘2’ would still repeat twice however it would begin
and end half-way through the timed item's iteration
interval.
Setting the iterationStart to a value greater than
or equal to one is typically only useful in combination with an
animation effect that has an accumulate property of
‘accumulate’.
- attribute unrestricted double iterations
-
The timed item's iteration count property.
A real number greater than or equal to zero (including positive
infinity) representing the number of times to repeat the
timed item.
Values less than zero and NaN values are treated as
the value 1.0 for the purpose of timing model calculations.
- attribute (unrestricted double or DOMString) duration
-
The iteration duration which is a real number greater than
or equal to zero (including positive infinity) representing the
time taken to complete a single iteration of the timed
item.
The string value auto is used to indicate that the
iteration duration reflects the timed item's intrinsic
iteration duration.
Real numbers less than zero, NaN values, and strings
other than the lowercase value auto are treated
the same as auto for the purpose of timing model
calculations.
Should we allow strings such as "3s" here?
i.e. a CSS <time>.
It might be useful for readability but introduces complexity when
handling this member (need to test the type, then possibly parse
the string).
It also introduces the issue of whether we should parse a full
clock
value.
- attribute double playbackRate
-
The timed item's playback rate property.
This is a multiplier applied to the local time potentially
causing the item to run at a different rate to its natural speed.
- attribute PlaybackDirection direction
-
The playback direction of the timed item as
specified by one of the PlaybackDirection enumeration
values.
- attribute DOMString easing
-
The timing function used to scale the time to
produce easing effects.
The syntax of the string is defined by the following production:
Unrecognized string values or values that correspond to
a timing function that is not supported for the type of
timed item to which this property is applied
are treated as if the linear keyword was specified
for the purpose of timing model calculations.
In future we may extend this so that it is possible to query the
individual functions in the string.
It may be possible to do this by extending this attribute using
some stringifier magic, or else we could just add
easingList similar to HTML's classList.
The TimingInput dictionary
The TimingInput dictionary is used as a convenience for
specifying the timing properties of a TimedItem in bulk.
- double delay = 0
-
The specified start delay.
See the description of the delay attribute on
the Timing interface.
- double endDelay = 0
-
The specified end delay.
See the description of the endDelay attribute on
the Timing interface.
- FillMode fill = "auto"
-
The fill mode as specified by one of the FillMode
enumeration values.
- double iterationStart = 0.0
-
The timed item's iteration start property.
See the description of the iterationStart attribute
on the Timing interface.
- unrestricted double iterations = 1.0
-
The timed item's iteration count property.
See the description of the iterations attribute
on the Timing interface.
- (unrestricted double or DOMString) duration = "auto"
-
The iteration duration of the timed item.
See the description of the duration
attribute on the Timing interface.
- double playbackRate = 1.0
-
The timed item's playback rate property.
See the description of the playbackRate attribute
on the Timing interface.
- PlaybackDirection direction = "normal"
-
The playback direction of the timed item.
See the description of the direction attribute
on the Timing interface.
- DOMString easing = "linear"
-
The timing function used to scale the time to produce
easing effects.
See the description of the easing attribute
on the Timing interface.
The FillMode enumeration
- none
-
No fill.
- forwards
-
Fill forwards.
- backwards
-
Fill backwards.
- both
-
Fill backwards and forwards.
- auto
-
Fill backwards and forwards when applied to a TimingGroup
and no fill when applied to an
Animation.
The PlaybackDirection enumeration
- normal
-
All iterations are played as specified.
- reverse
-
All iterations are played in the reverse direction from the way
they are specified.
- alternate
-
Even iterations are played as specified, odd iterations are played
in the reverse direction from the way they are specified.
- alternate-reverse
-
Even iterations are played in the reverse direction from the way
they are specified, odd iterations are played as specified.
The TimedItemList interface
A list of timed items may be represented by
a TimedItemList.
The TimedItemList interface supports indexed
properties with indices in the range 0 ≤ index <
length.
The only reason this interface exists is to provide a familiar
experience for authors familiar with DOM interfaces where child nodes
are accessed via a children member.
- readonly attribute unsigned long length
-
The number of timed items in the list.
- getter TimedItem? item(unsigned long index)
-
Returns the timed item at index.
If index is greater than or equal to
length returns null.
The ParGroup interface
Parallel timing groups are
represented by the ParGroup interface.
Some feedback indicates this naming is less than obvious.
The precedent is <par> from SMIL but
would ParallelGroup or Parallel be better?
Likewise for SeqGroup.
- Constructor ()
-
Creates a new ParGroup object using the following
procedure:
- Create a new ParGroup object, group.
- Set timing input as follows,
- If timing is a TimingInput object,
-
Let timing input refer to timing.
- If timing is a
double,
-
Let timing input be a new
TimingInput object with all members set to their
default values and
duration set to
timing.
- Otherwise (timing is undefined),
-
Let timing input be a new TimingInput
object with all members set to their default values.
-
Set
group.specified to a new
Timing object whose attributes are assigned the
value of the member of the same name on timing input.
The above two steps are identical with the constructor for Animation and should be
factored out somewhere.
-
Add children to the group by calling
group.splice(0, 0,
children).
Note that since Timing objects have the same member
names as TimingInput dictionaries, it is also possible to
pass the specified member of another
TimedItem as the timing parameter.
Doing so will cause the Timing object to be treated as
a TimingInput dictionary and thus it will effectively be
cloned, not shared.
- sequence<TimedItem>? children
-
A sequence of timed items to add as children of this group.
These children are appended in sequence using the same
semantics as the TimingGroup.append
method.
- optional (unrestricted double or TimingInput) timing
-
The timing properties or iteration duration of the new
timing group.
- ParGroup clone ()
-
Creates a deep copy of this ParGroup object using the
following procedure.
- Let source be this ParGroup object, the
object to be cloned.
- Let cloned timing be a new TimingInput
object whose members are assigned the value of the attribute
with the same name on
source.specified.
- Let cloned children be an empty sequence of
TimedItem objects.
- For each child in
source.children, append the result
of calling child.clone()
to cloned children.
- Return a new ParGroup object created by
calling the ParGroup constructor with parameters
ParGroup(cloned children,
cloned timing).
The SeqGroup interface
Sequence timing groups are
represented by the SeqGroup interface.
-
Constructor (sequence<TimedItem>? children,
optional (unrestricted double or TimingInput) timing)
-
The meaning and handling of each of the parameters in this
constructor is identical to the constructor for
ParGroup.
- SeqGroup clone ()
-
Creates a deep copy of this SeqGroup object using the same
procedure as defined for ParGroup.clone except
that a new SeqGroup object is created instead of
a ParGroup.
The Animation interface
Animations are represented by the
Animation interface.
- Constructor ()
-
Creates a new Animation object
using the following procedure:
- Create a new Animation
object, animation.
- Set timing input as follows,
- If timing is a TimingInput object,
-
Let timing input refer to timing.
- If timing is a
double,
-
Let timing input be a new
TimingInput object with all members set to their
default values and
duration set to
timing.
- Otherwise (timing is undefined),
-
Let timing input be a new TimingInput
object with all members set to their default values.
-
Set
animation.specified to a new
Timing object whose attributes are assigned the
value of the member of the same name on timing input.
- Assign the animation effect based on the type of
effect as follows,
- If effect is an AnimationEffect
object or an EffectCallback object,
-
Assign
animation.effect to
effect.
- If effect is a OneOrMoreKeyframes,
-
Set
animation.effect to
a new KeyframeEffect object constructed by
passing effect as the frames parameter
and with the other parameters set to their default values.
- Otherwise,
-
Set
animation.effect to
null.
Examples of the usage of this constructor are given in .
- Animatable? target
-
The animation target or target pseudo-element.
This may be
null for animations that do not target
a specific element.
- (AnimationEffect or EffectCallback or OneOrMoreKeyframes)? effect
-
The animation effect used to set the
effect
attribute of the newly-created Animation object.
If this parameter is an AnimationEffect object or
EffectCallback object, it will be shared with any
other Animation objects
referring to the same AnimationEffect or
EffectCallback object.
It will not be copied.
If this parameter of type OneOrMoreKeyframes,
the animation effect of the newly-created
Animation will be
a newly-created KeyframeEffect object
initialized by using this object as the list of
keyframes and with all other parameters set to their
default values.
If this parameter is null, the newly-created
Animation will also have
a null animation effect.
- optional (unrestricted double or TimingInput) timing
-
The timing properties or iteration duration of the new
animation.
- attribute (AnimationEffect or EffectCallback)? effect
-
The animation effect or custom effect to apply.
May be null in which case the animation will produce
no noticeable effect other than dispatching events (see ).
- readonly attribute Animatable? target
-
The element or pseudo-element being animated by this object.
This may be null for animations that do not target
a specific element such as an animation that produces a sound
using an audio API.
If SVG is extended to allow multiple targets (using, e.g.,
select="rect") then it might be most natural to
represent that in the API by allowing the target to
refer to multiple elements.
It's something that deserves attention for version 1.
- Animation clone ()
-
Creates a copy of this Animation object using the following procedure.
- Let source be the Animation object to
clone, that is, this object.
- Let cloned timing be a new TimingInput
object whose members are assigned the value of the attribute
with the same name on
source.specified.
-
The AnimationEffect is cloned depending on the type of
source.effect as follows,
- If
source.effect is an
Animation object,
-
Let cloned effect be the result of calling
source.effect.clone().
- If
source.effect is an
EffectCallback object,
-
Let cloned effect be
source.effect.
- Otherwise,
-
Let cloned effect be
null.
- Return a new Animation object created by
calling the Animation
constructor with parameters
Animation(source.target, cloned
effect, cloned timing).
Creating a new Animation object
The Animation constructor offers a number of approaches to
creating a new Animation object.
At its simplest, an Animation object that changes the
‘left’ property of elem to 100 over three
seconds can be achieved as follows:
var anim = new Animation(elem, { left: '100px' }, 3);
The second parameter, representing the animation effect, may
specify multiple properties, an AnimationEffect object, or
even a callback function.
// Specify multiple properties at once
var animA = new Animation(elem, { left: '100px', top: '300px' }, 3);
// Specify multiple frames
var animB = new Animation(elem, [ { left: '100px' }, { left: '300px' } ], 3);
// Share the animation effect of another animation
var animC = new Animation(elem, animB.effect, 3);
// Supply a specialized animation effect
var animD =
new Animation(elem, new MotionPathEffect("M100 250C100 50 400 50 400 250"), 3);
// Supply a custom script-based animation effect
var animE = new Animation(elem, function(time) {
// (Normally we should check for time===null, but in this case it produces
// the correct result anyway)
document.documentElement.currentScale = 1.0 + time * 2.0;
}, 3);
The third parameter representing the animation's timing, may
simply be a number representing the iteration duration as
above, or, to specify further timing properties such as the playback rate,
a TimingInput object can be used as follows:
var anim =
new Animation(elem, { left: '100px' }, { duration: 3, playbackRate: 2 });
It is also possible to omit the timing parameter altogether in which
case default timing values will be used.
Since the intrinsic iteration duration of an animation
is zero, and the default fill when constructing an
Animation is forwards, it is
possible to create animations that simply set a property without
any interpolation as follows,
new Animation(elem, { display: 'none' });
This is particularly useful in combination with other animations or timed
items.
For example, fading an element before switching
‘display’ to ‘none’ can be achieved as
follows,
new SeqGroup(
[
new Animation(elem, { opacity: '0%' }, 1),
new Animation(elem, { display: 'none' })
]
);
Having created an Animation, it
can be played using
document.timeline.play(anim).
For simple effects, the Element.animate
shortcut is more convenient since it performs this last step
automatically. For example,
elem.animate({ left: '100px' }, 3);
The Animatable interface
Objects that may be the target of an Animation implement the
Animatable interface.
- Animation animate()
-
Creates a new Animation object
whose animation target is the object on which the method is
called, and calls
the play
method of the Timeline object of
the document timeline of the node
document [[!DOM4]] of the element passing the newly created
Animation as the argument to
the method.
The following code fragment:
var anim = elem.animate({ opacity: '0' }, 2);
is equivalent to:
var anim = new Animation(elem, { opacity: '0' }, 2);
elem.ownerDocument.timeline.play(anim);
Returns the newly created Animation object.
- (AnimationEffect or EffectCallback or OneOrMoreKeyframes)? effect
-
The effect to apply.
This value is passed to the Animation
constructor as the effect parameter and has the
same interpretation as defined for that constructor.
- optional (double or TimingInput) timing
-
The timing parameters of the animation.
This value is passed to the Animation
constructor as the timing parameter and has the
same interpretation as defined for that constructor.
The AnimationEffect interface
Animation effects are represented by
the AnimationEffect interface.
AnimationEffect is an abstract interface of which several
concrete subinterfaces are provided.
- attribute AccumulateOperation accumulate
-
The accumulation operation property of this animation
effect as specified by one of the AccumulateOperation
constants.
- AnimationEffect clone ()
-
Creates and returns a new object of the same type as this object's
most-derived interface such that it will produce the same output
as this object.
We either need a more rigorous definition here or (probably
better) a sets of steps on a per-subclass basis.
In future, we may expose any sample (double? timeFraction,
double currentIteration, Animatable? target, any
underlyingValue) so that the animation effects can be driven
apart from the timing model.
The KeyframeEffect interface
Keyframe animation effects are represented by the
KeyframeEffect interface.
- Constructor ()
-
Creates a new KeyframeEffect object for the
given set of keyframes.
Before storing, each of the keyframes in frames is
normalized using the procedure in .
- OneOrMoreKeyframes frames
-
The set of keyframes used for calculating animation
values for this animation effect.
The constraints on this parameter and its processing are
identical to those for
setFrames.
- optional KeyframeEffectOptions options
-
A KeyframeEffectOptions dictionary defining other aspects
of the animation effect's behavior.
If this parameter is not provided, the default values of the
dictionary are used.
- attribute CompositeOperation composite
-
The composition operation used to composite this animation
with the animation stack, as specified by one of the
CompositeOperation enumeration values.
This is used for all keyframes that do not specify
a composition operation.
- attribute DOMString spacing
-
The spacing mode to use for
this animation effect.
Recognized values are defined by the following grammar:
distribute | paced({ident}) | paced
{ident} here is an identifier
as defined by CSS3 Values [[!CSS3-VALUES]].
The meaning of each value is as follows:
- distribute
- Use the distribute keyframe spacing mode.
- paced({ident})
-
Use the paced keyframe spacing mode with the property
name indicated by {ident} as the paced
property.
For example, paced(transform) would indicate that
the keyframes should be spaced such that changes to the transform property occur at
a constant rate.
- paced
-
Use the paced keyframe spacing mode.
The paced property to use is the first property
specified in the first keyframe in the list of keyframes
associated with this animation effect
when sorting the CSS property names in ascending order by
Unicode codepoint.
As a result, changes to the keyframes may cause the paced
property to change.
Note that this behavior is generally not useful for
keyframes specifying more than one property.
It is provided for consistency with
MotionPathEffect
and as a convenience for
keyframe animation effects
that specify only one property.
All other values are treated as "distribute" for the purpose of
animation model calculations.
- sequence<Keyframe> getFrames()
-
Returns the keyframes that make up this effect as
a sequence of Keyframe objects.
The value returned differs from the frames parameter
passed into setFrames or the constructor for this
interface in the following ways:
- The normalization defined in is applied to frames which
may result in some frames being removed or re-ordered and some
properties being removed.
- The result of computing the keyframe offset
of each Keyframe
as defined in is stored in the
computedOffset property of each frame as
a Number.
- void setFrames(OneOrMoreKeyframes frames)
-
Replaces the set of keyframes that make up this effect.
Upon setting, each keyframe in frames is normalized
using the procedure in before storing.
Normalizing a list of keyframes
For each call to setFrames or the KeyframeEffect
constructor the following normalization is performed on the passed
in frames parameter before storing its value.
- For each Keyframe object in
frames apply the normalization described in .
Any exceptions thrown that by procedure will likewise abort this
procedure.
- If frames is not loosely sorted by offset,
then,
- If each Keyframe has
a specified keyframe offset,
- Sort frames in ascending order by keyframe
offset.
- Otherwise,
- Throw a DOMException of type
InvalidModificationError.
- If there exist any Keyframe
objects in frames whose specified keyframe
offset is less than zero, remove all keyframes
objects from the start of frames up to and including
the keyframe with the largest specified keyframe offset
that is still less than zero.
- Likewise, if there exist any Keyframe objects in
frames whose specified keyframe offset
is greater than one, remove all keyframes from
keyframe with the smallest specified keyframe offset
that is still greater than one until the end of
frames.
- Remove all property values in frames that are invalid
or not supported by the implementation.
Normalizing a Keyframe object
Since accessing the properties of an ECMAScript user object can
have side effects, the manner in which these properties is
accessed is important.
In light of this consideration the procedure for normalizing
a Keyframe object has the
following properties:
- Each property that is read, is read only once.
- Properties are read in a well-defined order.
- Properties corresponding to unsupported target properties or
attributes are not read.
A Keyframe object, keyframe
input, is converted to a normalized internal representation
keyframe result using the following procedure:
- Let the initial keyframe offset
of keyframe result be
null.
- Let the initial composition operation
of keyframe result be
null.
- Create a list, supported properties, of property
names and attribute names that can be animated by the
implementation.
- Convert each property name in supported properties
to the equivalent IDL attribute by applying the CSS
property to IDL attribute algorithm [[!CSSOM]].
- If the user agent supports animation of the float CSS property, replace 'float' in
supported properties with 'cssFloat'.
- Let animation properties be an empty sequence.
- Iterate over the properties of keyframe input.
For each property in keyframe input,
perform the step corresponding to the first matching condition
from below, if any.
- If property is a case-sensitive match for
the string 'offset',
-
Set the keyframe offset of keyframe input to
the result of applying the procedure for
converting an ECMAScript value into an IDL double defined
in WebIDL [[!WEBIDL]] to
keyframe input.offset.
- If property is a case-sensitive match for
the string 'computedOffset',
-
Ignore property and continue to the next property.
- If property is a case-sensitive match for
the string 'easing',
-
Set the timing function of keyframe input
to the result of applying the
procedure for converting an ECMAScript value to an IDL
DOMString value defined in WebIDL [[!WEBIDL]] to
keyframe input.easing with the [TreatNullAs=EmptyString]
annotation in effect.
If the resulting string does not conform to the
grammar defined for the easing attribute
of the Timing interface or
is not supported by the implementation then
set the timing function of keyframe input
to the string “linear”.
- If property is a case-sensitive match for
the string 'composite',
-
Set the composition operation of keyframe
input to the result applying the
procedure for converting an ECMAScript value to an IDL
enumeration type defined in WebIDL [[!WEBIDL]] to
keyframe input.offset with
CompositeOperation as the enumeration type.
- Otherwise, if property also exists in
supported properties based on a case-sensitive
comparison,
- append property to animation
properties.
- For user agents that support both a prefixed and an
unprefixed version of some CSS properties, remove all
prefixed properties from animation properties
where the corresponding unprefixed version is also
present in animation properties.
I'd like to remove this step.
Prefixes are history.
- Sort animation properties lexicographically by
the Unicode codepoints that define each element.
- Iterate over animation properties and for each
element, name, add a new property-value pair to
keyframe result as follows:
- property name: the result of applying the
the IDL
attribute to CSS property algorithm [[!CSSOM]] to
name unless name is
a case-sensitive match for the string 'cssFloat' in
which case use the string 'float'.
- property value: the result of calling
toString on the name property of
keyframe input.
If the name property of keyframe input
is null or undefined, let the property value be an empty
string.
- Return keyframe result.
The above algorithm gives special meaning to the property names
'offset', 'computedOffset', and 'composite'.
If a CSS property called 'offset' or 'composite' is ever
introduced it will clash with the meaning here.
We have a few options:
- Add special handling at that time to allow addressing the
property of the same name, e.g.
cssOffset.
- Rename these keywords now to avoid risk of a later clash,
e.g. 'keyframeOffset'.
The Keyframe dictionary
Individual keyframes are represented by a special kind of
Keyframe dictionary type whose
members map to the properties to be animated.
At the time of writing, this kind of open-ended dictionary cannot
be represented using WebIDL and hence special
ECMAScript-specific handling for this type is defined in
.
No handling is defined for other languages.
- // ... property-value pairs ...
- double? offset = null
-
The keyframe offset of the keyframe specified as
a number between 0.0 and 1.0 inclusive or null.
Keyframes with offsets outside the range [0.0, 1.0] are
ignored when calculating animation values as defined in
.
A null value indicates that the keyframe
should be positioned using the keyframe animation effect's
keyframe spacing mode.
- DOMString easing = "linear"
-
The timing function used to transform the progress of time
from this keyframe until the next keyframe in the series.
The syntax and error-handling associated with parsing this string
is identical to that defined for the easing attribute
of the Timing interface.
- CompositeOperation? composite = null
-
The composition operation used to combine the values
specified in this keyframe with the underlying value.
If null, the composition operation
specified on the KeyframeEffect will be used.
The OneOrMoreKeyframes typedef
Throughout this specification we use the
OneOrMoreKeyframes
type to represent either a single keyframe or a list of such
keyframes.
The EffectCallback callback function
Custom effects can be defined in script by providing an
EffectCallback callback function.
An EffectCallback is called each time an Animation with which it is
associated is sampled.
- double? timeFraction
-
The time fraction for which to produce an effect.
When this is
null, the function SHOULD
remove the effect.
- Animation animation
-
The Animation object that is
being sampled.
- double? previousTimeFraction
-
The value of timeFraction that was passed to this
EffectCallback when it was previously called in the
context of sampling the same Animation that generated the
current call.
If this EffectCallback has not previously been called
within the context of sampling the same Animation as
with the current call, or if the time fraction was
null on the previous call, this parameter will be
null.
The TimingEvent interface
- Constructor ()
-
Constructs a new TimingEvent object as described in Constructing
events in [[!DOM4]].
- DOMString type
-
The type of timing event corresponding to one of the
types defined in .
- optional TimingEventInit eventInit
-
The parameters of the new TimingEvent.
- attribute double? localTime
-
The event local time.
This is the same time space used for startTime and
endTime on TimedItem.
This is the most useful time space if, for example, you receive
a timing event and want to add a new animation that
synchronizes with the item that dispatched the event by adding it
to the same timing group.
- attribute double? timelineTime
-
The event timeline time.
I think timeline time will be much more useful than global time.
For the rarer case that you want to synchronize animations
between documents using events, methods on
Timeline will
assist the conversion.
- attribute unsigned long? iterationIndex
-
The event iteration index.
- attribute boolean? seeked
-
The seeked dispatch flag.
The TimingEventInit dictionary type is used to specify the
parameters when constructing a TimingEvent object.
- double? localTime = null
- double? timelineTime = null
- double? iterationIndex = null
- boolean? seeked = null
Extensions to the Element interface
Since DOM Elements may be the target of an animation,
the Element
interface [[!DOM4]] is extended as follows:
This allows the following kind of usage.
elem.animate({ color: 'red' }, 2);
Furthermore, the following additional methods allow querying
the animated state of an element.
- sequence<Animation> getCurrentAnimations()
-
Returns the set of current Animation objects that have an animation
effect whose target is the Element on which this method
is called.
Note that this does not include
PseudoElements associated with this Element.
The returned list of Animation
objects is sorted by their associated animation effect
using the procedure defined for sorting animation effects
in .
- sequence<Player> getCurrentPlayers()
-
Returns the set of Player objects
whose source content is current and contains at
least one animation whose animation target is this
Element.
If this Element is the animation target of two or more animations which are associated with the
same player, the corresponding Player object will still only appear
in the returned list once.
The returned list is sorted in increasing order by player
sequence number.
The primary use case for this method is an application that
wants to increase the speed of all animations targetting
a particular element by a factor of 2 (not sure why and never
mind that this will affect all sorts of other elements too).
With only getCurrentAnimations a naïve author might
write:
elem.getCurrentAnimations().forEach(
function(anim) {
anim.player.playbackRate *= 2;
}
);
However, if elem is the animation target for
two animations that have the same player, then those animations
will be sped up by a factor of 4.
Instead the author needs to generate a unique list of players
first, hence this method.
Is this kind of situation common enough to warrant this method?
Or is it likely that when performing this kind of operation
you're mostly working with single animations and not timing
groups (as otherwise this operation could affect many other
elements)?
Your feedback is most welcome at public-fx@w3.org, subject
[web-animations] ….
Extensions to the PseudoElement interface
Since animations may also target
pseudo-elements, the PseudoElement
interface [[!CSSOM]] is also defined to be animatable.
This interface is marked at-risk in the 5 December 2013 WD
of CSSOM.
If it is removed, we will need to provide an equivalent definition
here.
Script execution and live updates to the model
The interaction between script execution and the state of
the model is as follows:
-
Changes made to the Web Animations model via the script interface
are reflected immediately in the values returned by the interfaces
defined in this specification.
Similarly, methods that operate on the current state of the model
such as pausing or reversing are applied to a fully-updated timing
model, that is, after all previous modifications have been
incorporated.
-
Changes to the model other than seek operations do not cause
timing events to be queued
immediately.
Instead, such events are queued upon the next sample as defined
in .
The behavior of events with relation to seek operations is defined
in .
Operations such as updating
the playback rate of a player that involve performing a seek operation cause events to be queued
immediately.
-
Modifications to the model using the script interface do not cause
the properties of the animation target to be updated and nor is
any CustomEffect called until the next sample has been
performed at some time after the current script block completes
execution.
I'm unsure if this is the desired behavior for actions such as
seeking and play() (and thus
animate()).
Gecko, for example, forces a synchronous sample when a seek is
performed.
This certainly makes testing simpler but I'm not sure if this is
a good idea or not.
-
The value returned by the currentTime attribute of
a document timeline will not change within a script block.
We may introduce timelines that can be started programmatically
(e.g. for SVG).
In such a case, the currentTime should probably
become zero immediately which would violate this
condition.
If we do indeed want that then we should probably spec it to force
a synchronous sample at that point and note it as an exception
here.
