Timing control for script-based animations

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.

Example

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; 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>

2. Conformance

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:

conforming user agent: A user agent is considered to be a conforming user agent if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification. A conforming user agent MUST also be a conforming implementation of the IDL fragment in section 4 of this specification, as described in the Web IDL specification. [WEBIDL]

This specification references interfaces and types from a number of other specifications:

Document [DOM3CORE]
Window [HTML5]
ElementTimeControl [SVG11]
DOMTimeStamp [WEBIDL]

3. Definitions

The native animations in a Document include all of the following, if the user agent implements the relevant specification:

SVG animations [SVG11]
CSS transitions [CSS3-TRANSITIONS]
CSS animations [CSS3-ANIMATIONS]

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.

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]

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.

Note

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:

Let t be the result of getting the next sample time of the Document.
Let time be t expressed as the number of milliseconds since 1970-01-01T00:00:00Z.
Let list be a copy of the Document’s animation frame request callback list. list will be empty if no script-based animations have been scheduled.
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:
1. If the callback has not been cancelled:
If no callbacks were fired in this iteration of the invocation algorithm, terminate these steps.

Note

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.

Note

Determining visibility precisely in all cases for all possible rendering models is a difficult task. If in doubt, it is always safe to assume that an element may be visible, while it is not safe to declare that an element is not visible if it might be.

5. Acknowledgements

This section is informative.

The editor would like to thank the following people for contributing to this specification: some people here.

Timing control for script-based animations

W3C Editor’s Draft 22 February 2011

Abstract

Status of this Document

Table of Contents

1. Introduction

2. Conformance

3. Definitions

4. The WindowAnimationTiming interface

5. Acknowledgements

A. References

A.1. Normative references

A.2. Informative references

B. Changes