Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
This specification was written based on the mozRequestAnimationFrame
feature implemented in Firefox.
Et cetera.
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.
<!DOCTYPE html> <title>Script-based animation using requestAnimationFrame</title> <style> div { position: absolute; left: 10px; top: 10px; padding: 50px; background: crimson; color: white } </style> <script> function animate(time) { document.getElementById("animated").style.left = (time - animationStartTime)%500 + "px"; window.requestAnimationFrame(animate, document.getElementById("animated")); } function start() { animationStartTime = Date.now(); window.requestAnimationFrame(animate, document.getElementById("animated")); } </script> <div onclick="start()" id="animated">Click me!</div>
Everything in this specification is normative except for diagrams, examples, notes and sections marked as being informative.
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels. [RFC2119]
The IDL fragment in section 4 of this specification MUST be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
This specification defines a single conformance class:
This specification references interfaces and types from a number of other specifications:
Document
[DOM3CORE]Window
[HTML5]ElementTimeControl
[SVG11]DOMTimeStamp
[WEBIDL]The native animations in a
Document
include all of the following, if the user agent implements the relevant specification:
A native animation is considered to be active if the current time is between the animation’s start and end time (inclusive), or if it has ended but has not yet been sampled for the frame immediately after its cessation.
As distinct from native animations, a script-based animation is one that is implemented manually by an author by continually manipulating the DOM.
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]
Associated with every Document
is a animation frame request callback list,
which is a list of FrameRequestCallback
objects and which initially is an empty list.
A Document
is said to have active animations
whenever it has a non-empty animation
frame request callback list.
[Supplemental, NoInterfaceObject] interface WindowAnimationTiming { long requestAnimationFrame(in FrameRequestCallback callback, in Element element); void cancelRequestAnimationFrame(in long handle); }; Window implements WindowAnimationTiming; [Callback, NoInterfaceObject] interface FrameRequestCallback { void sample(in 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 callback to the end of L. requestAnimationFrame
returns a user-agent-defined integer handle to identify this callback.
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.
When cancelRequestAnimationFrame
method is called,
the user agent MUST remove the callback associated with handle from L, if such a callback exists.
While a Document
has active animations, the user agent
MUST continually sample all animations.
To sample all animations,
the following steps are performed:
Document
.Document
’s
animation frame request callback list. list will be empty
if no script-based animations have been scheduled.The invoke callbacks algorithm:
requestAnimationFrame
operation of
callback with time as the argument.The purpose of this algorithm is to ensure that the callback for all potentially visible elements is invoked for a frame even if a side effect of invoking one callback changes the visibility of an element associated with another callback.
An element may be visible if the user agent determines that some portion of the element may be displayed.
This section is informative.
The editor would like to thank the following people for contributing to this specification: some people here.
There are no informative references.
The following is a list of substantial changes to the document on each publication.