Timeline
interfaceThis is basically supposed to be a method that answers the question, "If the time of this timeline is A (timelineTime), what will the local time be at timed item B (target)?"
Returns the corresponding time value for a given timed item, target, for a time value relative to this timeline using the following procedure.
All the following needs to be updated since it refers to time sources etc.
timeline
property on A if
such a property exists and refers to a TimeSource
object.DOMException
of type
HierarchyRequestError
.
toDocumentTime(documentTime,
remote document)
on this object.
currentTime
of other by
following the steps described somewhere...
Exceptions:
HierarchyRequestError
Is this needed? And is the automatic cross-document time source negotation required?
TimingFunctionCallback
callbackIn addition to the timing functions provided by Web Animations, authors may also provide their own time scaling function. The behavior of this function is defined by the TimingFunctionCallback type below.
A TimingFunctionCallback function has the same behavior as
defined for the scaleTime
method on the
TimingFunction interface.
That is, it takes an input time fraction, applies some scaling
operation to it, and returns an output time fraction.
For the same input time
and item
, this
function MUST return the same output.
As a result, a user agent MAY cache the results returned by
a TimingFunctionCallback as an optimization.
Note, however, that if the item
object is changed, this
consitutes different input to the function and hence the user agent
MUST NOT cache the results of the callback if the item
object changes.
Given the requirement that callback functions do not change
item
, a user agent can expect that it is safe to cache
the output of a TimingFunctionCallback for at least the
duration of a sample.
Is it important to be able to differentiate between when the scaling is being applied to an iteration as a whole or simply to a segment of a keyframe animation?
I suspect it probably is and that that would consitute different input to the function.
Needs to be adjusted as follows:
Let scaled iteration time be
unscaled iteration time *
timing.timingFunction.scaleTime(unscaled iteration
time / iteration duration)))
.
Let scaled iteration time be
unscaled iteration time *
timing.timingFunction(unscaled iteration
time / iteration duration)))
.
If calling timing.timingFunction
results in an exception being thrown, let scaled
iteration time be unscaled iteration time.
Need to consider:
TimedItem.iterationTime
result in the
script being executed every time?
Possibly could define things such that iteration time
is evaluated on each sample (need to define sampling)
and then only if iterationTime
is
explicitly requested (i.e. no caching there)... what
about other operations that rely on iteration time
being up to date? what are they?
TimedItem.iterationTime
should use
a cached value in that case)It is sometimes necessary to apply the same animation effect to a series of targets. Animation templates provide a means for the same set of animation properties to be applied repeatedly to a number of targets whilst maintaining a link such that changes to the template are reflected at each place where the template is applied.
In concrete terms, an AnimationTemplate object is used to create
multiple Animation objects each of which maintains a link back to
the template via its template
property.
Such Animation objects are said to be linked to
a template.
The timing and animation parameters of linked animations cannot
be modified directly.
Rather, changes are made to the template which is then echoed to all
animations linked to the same template.
In order to modify the timing and animation parameters of
a linked animation directly, it must first be unlinked using the
unlink
method.
Note that run-time properties of a linked animation such as its
start time and time drift can still be modified.
Only those properties attached to the timing
and
effect
properties of a linked Animation
object are read-only.
Unlinked animations can be linked to a template by:
templatize
to create a new
AnimationTemplate with properties set to reflect the current
state of the Animation object on which it is called.Provide some javascript sample here demonstrating?
For linked animations (see ), the AnimationTemplate object
from which this object derives its values.
For animations that are not linked to a template, this property is
null
.
Setting this property has the following effect:
template
property.null
,
unlink()
.timing
to new
template.timing.clone()
.effect
to new
template.effect.clone()
.template
to new
template
.If this object is not already linked to a template, creates a new AnimationTemplate object based on this object and links this object to it (see ).
What is the more useful behavior? To always create a template? Or to only create one if it doesn't already have one?
The effect is equivalent to the following steps:
templatize
is called.source.template
is not
null
, return.template.timing
to
source.timing.clone()
.template.effect
to
source.effect.clone()
.source.template
to
template.Makes this animation independent of the template with which it is associated if any (see )
After setting template
to null
the
previous value of template
is returned.
The effect is equivalent to the following steps:
template
is null
, return
null
.template
.timing
to
template.timing.clone()
.effect
to
template.effect.clone()
.template
to null
(but do not
recursively call this function).AnimationTemplate
interface
TimedTemplate
interface
Both the timing of an AnimationTemplate
and the methods
for creating an Animation
from an
AnimationTemplate
are specified on the
TimedTemplate
since this behavior is shared with
animation groups (see ).
Should we allow live lists to be passed in? i.e. selectors etc.?
Creates an independent TimedItem
and appends it
to element.ownerDocument.animationTimeline
.
This allows the following sort of usage:
anim.animate(document.getElementById("a"));
The specific steps for instantiating a
TimedTemplate
depends on its concrete type and is
described in and .
The start time for the generated animations
expressed in seconds in the iteration time space of the
AnimationGroup
to which it is
appended (see ).
If this parameter is not specified it will default to the
current iteration time of the
AnimationGroup
to which it is
appended if it is not null
, otherwise it will
default to zero.
Creates a series of independent TimedItem
objects, one for each element in target
.
As with animate(AnimationTarget target, double
startTime)
each such TimedItem
object is
appended to element.ownerDocument.animationTimeline
.
This allows the following sort of usage:
anim.animate([document.getElementById("a"), document.getElementById("b")]); anim.animate(document.querySelectorAll("div.warning")); anim.animate(document.getElementsByTagName("button")); anim.animate(document.getElementById("group").childNodes);
The specific steps for instantiating a
TimedTemplate
depends on its concrete type and is
described in and .
Node
s to be animated.
Any nodes in the sequence that are not of type
ELEMENT_NODE
will be ignored.
animate(AnimationTarget target, optional double
startTime)
.
Similar to animate
, this method creates
independent TimedItem
object(s) for the
elements in target
.
However, the resulting items are appended to the given
parentGroup
, if provided.
If parentGroup
is null
, the
TimedItem
objects will not be added to any
group.
animate
.
The start time for the generated animations
expressed in seconds in the iteration time space of the
AnimationGroup
to which it is
appended (see ).
If this parameter is not specified it will default to the
current iteration time of parentGroup
.
If parentGroup
is null
,
this parameter will default to zero.
animateWithParent(AnimationTarget target,
AnimationGroup? parentGroup,
optional double startTime)
except
one TimedItem
is created for each
Node
in target
that is of type
ELEMENT_NODE
.
animate
with the exception that the
TimedItem
objects generated by this method are
live.
animate
with the exception that the
TimedItem
objects generated by this method are
live.
animateWithParent
with the exception that the
animations generated by this method are live.
animateWithParent
with the exception that the
animations generated by this method are live.
AnimationTemplate
The procedure for instantiating an AnimationTemplate
,
template, given a list of target elements and an optional
parent group, is as follows:
Animation
objects.
Animation
object, anim.
timing
and effect
properties of anim to copies
template.timing
and
template.effect
.
element.ownerDocument.animationTimeline
.
Animation
objects.
Animation
objects.
As with animations, templates can also be created for animation groups.
Lots of questions here about how this should work.
AnimationGroupTemplate
interfaceTBD
index
.
If index
is greater than or equal to
length
returns null
.
Replaces the item at index
with
newItem
by calling
splice(index, 1, newItem)
.
Returns newItem
.
The behavior of this method is identical to
the equivalent setter in AnimationGroup
except that DOMExceptions of type HierarchyRequestError are not
thrown.
Add newItem
and each otherItems
as the
last item(s) in the group by calling splice(group.length, 0,
newItem, otherItem1, ... otherItemN)
.
Returns a sequence containing the added items:
[newItem, otherItem1, ... otherItemN]
.
Removes the item(s) at index
by calling
splice(index, count)
.
Returns the removed items.
Modifies the list of children of this group by first removing
deleteCount
items from start
followed by
adding newItems
at the same point.
Returns a sequence of the items removed from group during the removal step (regardless of whether these items were re-added during the addition step).
As with AnimationGroup.slice
the operation of
slice is based on ECMAScript
5's Array.prototype.splice.
The operation of this method is identical to that of
AnimationGroup.slice
with the notable difference
that DOMExceptions of type HierarchyRequestError are not thrown
since there is no AnimationGroupTemplate
corresponding to a document timeline.
length
,
length
].
start
.
Negative values are clamped to zero, and all other values are
clamped such that
0 < start
+ deleteCount
≤
length.
start
.
Each item, if it already has a parent group (including this
group), is first removed from its parent group before being
added to this group.
splice
to take a variadic list of items
rather than requiring a sequence.
The operation is identical to splice(unsigned long start,
unsigned long deleteCount, sequence<TimedTemplate>
newItems)
.
item
within the group.
If item
is not in the group, returns -1
.
ParGroupTemplate
interfaceParGroup objects can be created from ParGroupTemplate objects.
SeqGroupTemplate
interfaceSeqGroup objects can be created from SeqGroupTemplate objects.
AnimationGroupTemplate
TBD. This is probably all wrong.
The procedure for creating an AnimationGroup
from
an AnimationGroupTemplate
, template,
given a list of target elements, and optionally given a parent
group follows.
Note that ParGroupTemplate
objects produce
ParGroup
objects and likewise
SeqGroupTemplate
objects produce SeqGroup
objects.
In the following description the AnimationGroupTemplate
and AnimationGroup
types should be substituted with the
concrete types in use.
AnimationGroup
objects.
AnimationGroup
object,
group.
timing
property of group to
a copy of template.timing
.
child.animateWithParent(element,
group, startTime
)
or
child.animateLiveWithParent(element,
group, startTime
)
depending on
whether this procedure was invoked with animate
or
animateLive
.
element.ownerDocument.animationTimeline
.
AnimationGroup
objects.
AnimationGroup
objects.
I think we want two types of custom effects. Following is the general-purpose animate-anything kind of effect. The other type, which is not defined here, is the one that can participate in the animation sandwich just like any other.
This, second, native-like animation effect, would have the following features:
AnimationEffect.sample
That's a bit more difficult since you have to be careful that the custom effect doesn't do anything naughty while you're in the middle of compositing the animation sandwich. I think we should postpone this until Web Animations 2.
TimingFunction
interfaceThe timing functions provided by Web Animations share a common TimingFunction interface as defined below.
Takes an input time fraction in the range [0, 1] and applies some transformation on the value to produce an output time fraction.
The TimedItem for which the time scaling operation is being performed.
Some timing functions, for example, may produce different results depending on the animation values involved to produce an even rate of change.
This may be null
, for example, when invoked
directly by user code for the purpose of testing or re-using
the scaling operation in another context.
Implementations of this interface for which there is no
meaningful result in the absence of a TimedItem will
simply return time
unchanged when
item
is null
.
Exceptions:
IndexSizeError
Should be just clamp x values to the range [0, 1] ?
For implementations of this interface that have local state, produces an identical but independent copy of this object. For implementations without local state, returns the same object.
Creates a new TimingFunction object based on a string-based specification (e.g. "ease-in").
The acceptable values and their meanings are those defined for the transition-timing-function property in CSS Transitions [[!CSS3-TRANSITIONS]].
In addition to the values defined in CSS Transitions, this method
extends the steps()
function notation to allow
‘middle’ as a transition point keyword (e.g.
steps(3, middle)
) corresponding to the
‘middle’ StepPosition value.
Similarly, the keyword ‘steps-middle’ is recognized by
and given the meaning steps(1, middle)
.
Strings that specify a cubic-bezier()
timing function
result in a new CubicBezierTimingFunction being returned.
Strings that specify a steps()
function produce a new
StepTimingFunction.
If spec
is unrecognized, null
is
returned.
User agents that provide debugging feedback SHOULD report the
unrecognized value.
Should we make the ‘linear’ keyword return
null
or new CubicBezierTimingFunction([0, 0, 1,
1])
?
I think null
except that this may mark it
harder to detect error cases.
CubicBezierTimingFunction
interface
Cubic Bézier timing
functions are represented using the
CubicBezierTimingFunction
interface defined below.
Creates a new CubicBezierTimingFunction object and
initializes the points
member to the passed in list
of points
.
It would be more convenient for authors if the passed in list of points could be longer than four items and we simply read the first four items and ignored the rest. However, applications may begin to depend on that behavior and we could not easily allow this object to take longer lists (to represent more complex curves) in the future without adding a separate constructor for that purpose.
Exceptions:
IndexSizeError
points
is outside the range [0, 1]
or if the length of points
is not 4 items.
A sequence of four real numbers representing the coordinates of the two control points in the following sequence <p1-x> <p1-y> <p2-x> <p2-y>.
Each of the x values (i.e. p1-x and p2-x) must be in the range [0, 1].
Exceptions:
IndexSizeError
InvalidModificationError
points
.
points[0], points[1]
),
(points[2]
, points[3]
), (1, 1).
StepTimingFunction
interfaceStep timing functions are represented by the StepTimingFunction interface.
Creates a new StepTimingFunction with the specified number of steps and transition point.
Exceptions:
IndexSizeError
numSteps
is zero.
A number greater than or equal to one representing the number of steps in the function.
Exceptions:
IndexSizeError
numSteps
and position
with input
time.
The behavior of the step function is described in .
StepPosition
enumerationThe point within a step interval at which the change in value occurs is specified using one of the StepPosition enumeration values.
KeyframeList
interfaceThe KeyframeList object is a collection of Keyframe objects sorted by the offset of each Keyframe.
index
if it exists or
null
otherwise.
Adds frame to the list such that the list remains sorted by the offset of the frames.
If frame is of type KeyframeDictionary then
a Keyframe object is first constructed by calling
Keyframe(frame)
before adding the
newly constructed Keyframe to the list.
If there already exists a frame in this list with offset
frame.offset
, the newly added
frame will appear in the list after the
already existing frames in the list with the same offset.
If frame is already part of another KeyframeList it is first removed from that list before being added to this list.
Exceptions:
IndexSizeError
null
is
returned.
-1
.
Adjusts the offsets of the frames in the list such that the offsets are spaced equidistantly whilst maintaining their current order and such that the first frame (when there are multiple frames) has offset 0 and the last frame (if any) has offset 1.
For frame at position i in the list where
0 ≤ i < length
, an offset will be
assigned equal to i / (length - 1)
unless
length
is 1 in which case it will be given offset
1.
After applying the changes, this list is returned.
The following changes for making keyframes easier to work with in future have been proposed:
// Currently you have to do this effect.frames.add({ property: 'left', offset: 0.3, value: '100px' }); // It would be nice if you could also do this effect.frames.add(0.3, 'left', '100px'); // Also, fetching by offset would be good // Returns the last frame with offset 0.3 if there is one. // If there is none, does the interpolation and returns a new frame? var frame = effect.frames['0.3'];
Keyframe
interfaceAn individual key frame is represented by the Keyframe interface.
Currently a Keyframe can only target a single property which is defined on the KeyframeAnimationEffect. This is different to CSS. Is this something we want to change? It would complicate the API, of course, but is it worth it?
Creates a new Keyframe object using the parameters specified in dictionary.
dictionary.offset
is clamped to the
range [0, 1] before setting.
A value between 0 and 1 inclusive representing the offset within the iteration duration of the animation where this value should appear.
If this keyframe belongs to a KeyframeList, changes to this value cause the KeyframeList to be immediately re-sorted using a stable sort such that all children are ordered by their offset but children with identical offsets retain their relative position in the list.
Exceptions:
IndexSizeError
An optional timing function to apply between this keyframe and the next keyframe in any KeyframeList in which this object appears.
The acceptable values and the handling of unrecognized values is
identical to the behavior described for the
timingFunction
member of
TimingDictionary.
KeyframeDictionary
dictionary
To simplify creation of Keyframe objects
a KeyframeDictionary
can be used.
The members of the dictionary correspond to attributes in the Keyframe interface which provides a more complete description of their meaning and usage.
A string specifying the timing function to apply between this keyframe and the next keyframe in any KeyframeList in which this object appears.
The acceptable values and the handling of unrecognized values is
identical to the behavior described for the
timingFunction
member of
TimingDictionary.