Abstract
This document defines an API web page authors can use to write script-based
animations where the user agent is in control of limiting the update
rate of the animation. The user agent is in a better position to determine
the ideal animation rate based on whether the page is currently in a foreground
or background tab, what the current load on the CPU is, and so on. Using this
API should therefore result in more appropriate utilization of the CPU
by the browser.
Status of this Document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current W3C
publications and the latest revision of this technical report can be found in
the W3C technical reports index at
http://www.w3.org/TR/.
This document is the 17 February 2012 Last Call Working Draft of the
Timing control for script-based animations specification.
Please send comments about this document to
public-web-perf@w3.org
(archived)
with [RequestAnimationFrame] at the start of the subject line by 20 March 2012.
This document is produced by
the Web Performance
Working Group. The Web Performance Working Group is part of
the Rich Web Clients
Activity in the
W3C Interaction
Domain. Changes made to this document can be found in the
W3C
public Mercurial server.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the
5 February 2004 W3C Patent Policy.
W3C maintains a public list of any patent disclosures made
in connection with the deliverables of the group; that page also includes
instructions for disclosing a patent. An individual who has actual knowledge of
a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
1. Introduction
This section is informative.
Animations in web browsers come in two forms: native, declarative ones, such
as the <animate> element in SVG, and those that are implemented
in script. These script-based animations are most often performed by scheduling
a callback using setTimeout or setInterval and making
changes to the DOM to effect the animation in that callback.
A disadvantage of this approach is that the author of the animation script has
no idea what the ideal frequency for updating their animation is. Instead, the
easiest way forward for the author is to simply call setTimeout with
a very small value, which in practice will be clamped to some minimum time like
10ms anyway. It likely won’t be the case that 100 updates per second are required
for the animation, especially if the page is in a background tab or the browser
window is minimized.
The API described in this document allows script authors to request the user
agent schedule an animation frame update. The user agent is in a better position
to determine how many frames per second to allocate to all of the animations running
in the entire browser. If there are many animations active, the user agent can
select a frame rate such that all of the animations will run as smoothly as possible.
If the page is not currently visible, animations on that page can be throttled
heavily so that they do not update often and thus consume little CPU power.
Here is an example of using the API to write a script-based animation.
HTML
<!DOCTYPE html>
<title>Script-based animation using requestAnimationFrame</title>
<style>
div { position: absolute; left: 10px; padding: 50px;
background: crimson; color: white }
</style>
<script>
var requestId = 0;
function animate(time) {
document.getElementById("animated").style.left =
(time - animationStartTime) % 2000 / 4 + "px";
requestId = window.requestAnimationFrame(animate);
}
function start() {
animationStartTime = Date.now();
requestId = window.requestAnimationFrame(animate);
}
function stop() {
if (requestId)
window.cancelAnimationFrame(requestId);
requestId = 0;
}
</script>
<button onclick="start()">Click me to start!</button>
<button onclick="stop()">Click me to stop!</button>
<div id="animated">Hello there.</div>
4. The WindowAnimationTiming interface
The WindowAnimationTiming interface is used to expose the
requestAnimationFrame
operation on the Window
object. In the definition of requestAnimationFrame below, references to the
Document
object are to be taken to be references to the Window
object’s active document. [HTML5]
[NoInterfaceObject]
interface WindowAnimationTiming {
long requestAnimationFrame(FrameRequestCallback callback);
void cancelAnimationFrame(long handle);
};
Window implements WindowAnimationTiming;
callback FrameRequestCallback = void (DOMTimeStamp time);
The requestAnimationFrame method is
used to signal to the user agent that a script-based animation
needs to be resampled. When requestAnimationFrame(callback) is called, the user agent MUST schedule a script-based animation
resampling by appending to the end of the animation frame request callback list
an entry whose handle is a user-agent-defined integer greater than zero that uniquely identifies the entry in the list and
whose callback is callback.
Each FrameRequestCallback object has a cancelled boolean flag. This
flag is initially false and is not exposed by any interface.
requestAnimationFrame only schedules
a single update to the script-based animation. If subsequent animation frames are needed, then
requestAnimationFrame will need to be called
again from within the callback.
Also note that multiple calls to requestAnimationFrame with the same callback
(before callbacks are invoked and
the list is cleared) will result in multiple entries being in the list with that same callback,
and thus will result in that callback being invoked more than once for the animation frame.
ISSUE-4 Do we want to allow an Element to be passed
to requestAnimationFrame, so that animations affecting the given element are throttled or paused when scrolled out
of view?
The cancelAnimationFrame method is
used to cancel a previously made request to schedule an animation frame update. When cancelAnimationFrame(handle) is called,
the user agent MUST set the cancelled flag to true for the
callback registered on this Document whose handle is handle. The cancelled
flag is set whether the callback is in a animation frame request callback list or not.
If there is no callback with the given handle, then this function does nothing.
5. Processing Model
Whenever a
Document's
hidden attribute is false
and the
animation frame request callback list is not empty, the user agent MUST
regularly
queue a
task that
samples all animations for that
Document's
top-level browsing context.
The
task source
for these
tasks is the
animation task source. Only one
task should be generated per
top-level browsing context, even if multiple
Documents within the same
top-level browsing context are not hidden and contain callbacks.
To
samples all animations , the following steps are performed:
- Let t be the result of getting the next sample time
of the top-level browsing context.
ISSUE-2 Getting the next sample time
is currently undefined. This time should be the same as the time that contemporaneous native animations have been sampled at.
- Let time be t expressed as the number of milliseconds since 1970-01-01T00:00:00Z.
ISSUE-3 Having animation frame times run off a
monotonic clock that increases at a constant rate would be better for authors than using the wallclock time
as reported by the system, which might jump backwards or move forwards at varying rates due to clock slew.
Doing this argues for the reinclusion of the Window.animationStartTime attribute that was present in an earlier
draft, so that scripts can avoid using Date.now() to record the animation start time,
which might bear little relation to the monotonic clock values anyway.
- Let list be an empty animation frame request callback list.
- Let contexts be the results of list of the descendant browsing contexts algorithm for this task's top-level browsing context.
- For every context in contexts, in any order, perform the following steps:
- Let d be context's active document.
- If d's hidden
attribute is true, continue to the next entry in the contexts list. Otherwise proceed with these steps.
- Let doclist be d's animation frame request callback list.
- Append all entries from doclist into list preserving order.
- Clear doclist.
- Perform the steps defined in the invoke callbacks algorithm with parameters list and time
The invoke callbacks algorithm:
- For each entry callback in list, in order:
- If the cancelled flag on callback is not true:
- Call callback with time as the argument.
- If calling the operation resulted in an exception being thrown, then catch that exception and ignore it.
The expectation is that the user agent will run tasks from the animation task source at
at a regular interval matching the display's refresh rate. Running tasks at a lower rate can result in animations not appearing smooth. Running tasks
at a higher rate can cause extra computation to occur without a user-visible benefit.
6. Acknowledgements
This section is informative.
The editors would like to thank the following people for contributing to
this specification: Boris Zbarsky, Jonas Sicking, Robert O’Callahan.