Adds a method to determine if an animation requires refresh driver ticks.
We will use this function later to determine when it is safe to stop
observing the refresh driver.
This patch adds a utility method to Animation which takes a time in the
same time space as "current time", i.e. "animation time" and convert it to
a TimeStamp. Subsequent patches in this series will use this method to
take the time when an event was scheduled to occur and convert it to a
TimeStamp so it can be compared with other event times. This allows us to
dispatch events in the order they would have fired given an infinitely
frequent sample rate.
The Web Animations specification has replaced the term "sequence number" with
references to a global animation list. This patch applies similar naming
to our animation structures.
We currently determine if we need refresh driver ticks when composing style
but sometimes we might not need ticks for composing style but we might need
one more tick in order to queue a final end event. Currently, this doesn't
seem to be a problem because FlushAnimations calls Animation::Tick where we
queue up events. When we remove the call to Animation::Tick from
FlushAnimations in order to make FlushAnimations purely responsible for
posting restyles, however, we will create a situation where we might mark an
animation collection as no longer needing refreshes and not simultaneously
queueing the corresponding event. If another animation collection is deleted in
the meantime we may trigger the code that causes us to disassociate from the
refresh driver and the corresponding event will never be dispatched.
Long-term (bug 1195180) we will check if it we can stop observing the refresh
driver and queue events in the same step. Until then, this patch adds a method
to detect this particular situation and uses it to avoid unregistering from
the refresh driver while we still have end events to queue.
The long-term plan is to drop the mozilla::css namespace altogether. Before we
go to much further with refactoring code in AnimationCommon, we should drop
usage of the mozilla::css namespace. Specifically, this patch moves the
CommonAnimationManager and AnimValuesStyleRule classes to the mozilla namespace.
This patch prepares the way for script-generated events by making
event dispatch a separate process that happens after sampling animations.
This will allow us to sample animations from their associated timeline
(removing the need for a further manager to tracker script-generated
animations).
Furthermore, once we sample animations from timelines the order in which they
are sampled is likely to be more or less random so by making event dispatch at
separate step, we have an opportunity to sort the events and dispatch in
a consistent and sensible order. It also ensures that event callbacks will
not be run until all animations (including transitions) have been updated
ensuring they see a consistent view of timing properties.
This patch only affects event handling for CSS animations. Transitions will
be dealt with in a subsequent patch.
The long-term plan is to drop the mozilla::css namespace altogether. Before we
go to much further with refactoring code in AnimationCommon, we should drop
usage of the mozilla::css namespace. Specifically, this patch moves the
CommonAnimationManager and AnimValuesStyleRule classes to the mozilla namespace.
This patch prepares the way for script-generated events by making
event dispatch a separate process that happens after sampling animations.
This will allow us to sample animations from their associated timeline
(removing the need for a further manager to tracker script-generated
animations).
Furthermore, once we sample animations from timelines the order in which they
are sampled is likely to be more or less random so by making event dispatch at
separate step, we have an opportunity to sort the events and dispatch in
a consistent and sensible order. It also ensures that event callbacks will
not be run until all animations (including transitions) have been updated
ensuring they see a consistent view of timing properties.
This patch only affects event handling for CSS animations. Transitions will
be dealt with in a subsequent patch.
This is in anticipation of adding Animation::SetTimeline(). Once we set the
timeline out of band, there's a chance that getting it could return null so
this patch makes the WebIDL and method name reflect that.
The connection between an Animation and an AnimationTimeline is optional. That
is, it is possible to have an Animation without an AnimationTimeline. Until now
we have often just assumed the timeline will be set but eventually we need to
support the possibility of the timeline being null. Indeed, later in this patch
series we will set the timeline out-of-band (i.e. not in the constructor) using
SetTimeline which opens up the possibility that timeline will be null for
a period of time.
This patch paves the way for having an optional timeline by storing the global
used for, e.g. creating promises, on the Animation object itself.
This patch also extends the tests for Element.getAnimations(). It doesn't
actually exercise the code added (it's not actually called yet since it doesn't
need to be for Element.getAnimations) but simply provides a useful regression
and interop test.
Add a virtual method we can use to determine when an animation is having its
sequence number set by some other mechanism than the general logic
defined for animations.
This allows CSS animations and transitions to re-use the sequence number for
their own purposes. Typically what will happen is something like this:
1. A CSSAnimation is created corresponding to an item in the animation-name
property.
At this point CSSAnimation::IsUsingCustomCompositeOrder() will return true
and nsAnimationManager will set the sequence number based on the position of
the animation in animation-name.
2. If at a later point the animation is removed from the animation-name but kept
alive by script, CSSAnimation::CancelFromStyle will be called which will
clear the custom sequence number (i.e. set it to kUnsequenced) and also
update the CSSAnimation's state such as
CSSAnimation::IsUsingCustomCompositeOrder() returns false.
3. Then, then the CSSAnimation next transitions out of the idle state it will
have its sequence number set just like any other Animation and be ordered
like any other Animation (since we can no longer use animation-name to
determine its composite order).
This behavior is added in subsequent patches in this series (and likewise for
CSS transitions too).
This patch introduces a method that will be used for sorting animations based on
their composite order. The method is based on the API for Comparator objects (as
used by nsTArray and co.) which have a LessThan method. (For the
Comparator::Equals method we can used pointer equality since no two independent
objects should have equal composite order.)
Web Animations defines Animations as having a globally unique sequence number
for the purpose of prioritization:
http://w3c.github.io/web-animations/#animation-sequence-number
As of the writing of this patch, the spec says the sequence number is updated
when the Animation is created. This is problematic and I have proposed that
actually this should be updated from each transition from idle:
https://lists.w3.org/Archives/Public/public-fx/2015AprJun/0054.html
This doesn't seem to have met any opposition so I will update the spec to
reflect this soon.
This patch implements the behavior of updating the sequence number on each
transition from idle.
To make sure we perform this on each change to timing this patch removes
a couple of instances of early returns to ensure that UpdateTiming is called.
The current maximum sequence number is simply a class static and we make no
attempt to deal with wraparound. This is because we only update this number when
an animation transitions from idle which only happens when an animation is
created or script calls cancel() followed by play() on the animation. Supposing
that across all content this happenned an unlikely 1 billion times a second we
still wouldn't exhaust the range of the unsigned 64-bit int for about 585 years.
We'd like to make kUnsequenced be zero and make the static represent the
current maximum. This would probably be easier to understand and recognize in
a debugger. However, later in this patch series we will make CSS animations and
CSS transitions override this sequencing behavior. If we define kUnsequenced
to be zero and they accidentally assign zero as an actual sequence number then
they'll run into trouble. To avoid that we set kUnsequenced to UINT64_MAX.
In order to sort CSS animation objects correctly, we need to know which
element's animation-name property they appear in, if any. Normally that's
simply the target element of the animation's keyframe effect but it can differ
in the following cases:
1) When script modifies a CSSAnimation's effect to target a different element
(or simply removes the effect altogether). In this case we use the
*owning* element to determine the priority of the animation, not the target
element.
This scenario does not yet occur (bug 1049975).
2) When script creates a CSSAnimation object using the CSSAnimation constructor.
In this case, the owning element should be empty (null) and we should
determine the priority of the animation in the same way as any other
Animation object.
Again, this is not yet supported (or even specced) but will be eventually.
3) When script holds a reference to a CSSAnimation object but then updates the
animation-name property such that the animation object is cancelled. In this
case the owning element should be cleared (null) so we know to not to try and
sort this with regard to any animation-name property.
This is possible using code such as the following:
elem.style.animation = 'a 5s';
var a = elem.getAnimations()[0];
elem.style.animation = 'b 5s';
a.play(); // Bring a back to life
document.timeline.getAnimations();
// ^ At this point we need to know how to sort 'a' and 'b' which depends
// on recognizing that a is no longer part of an animation-name list.
Until we implement bug 1049975, we could support sorting animations without
adding the reference to the owning element by setting a flag on the CSSAnimation
object but (having tried this) it turns out to be cleaner to just introduce this
reference now, particularly since we know we will need it later.
Note that we will also need this information in future to dispatch events to the
correct element in circumstances such as (1) once we separate updating timing
information (including events) from applying animation values.
This patch makes Cancel() call PostUpdate which clobbers certain state in style
so that animated style is correctly flushed when an animation is cancelled.
The main difficulty with this is that we *don't* want to call this when we're
cancelling an animation as a result of a style update or else we'll trigger
needless work. The pattern elsewhere has been to define a *FromStyle() method
for this case (e.g. CSSAnimation::PlayFromStyle, PauseFromStyle). This isn't
ideal because there's always the danger we will forget to call the appropriate
*FromStyle method. It is, however, consistent. Hopefully in bug 1151731 we'll
find a better way of expressing this.
