index.html 23.4 KB

Raw Blame History Permalink

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <title>Timing control for script-based animations</title>
  <link rel="stylesheet" href="RequestAnimationFrame.css" type="text/css" />
  <script src="section-links.js" type="application/ecmascript"></script>
  <script src="dfn.js" type="application/ecmascript"></script>


<link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD" type="text/css" /></head>

<body>
<div class="head"><div><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" width="72" height="48" alt="W3C" /></a></div><h1>Timing control for script-based animations</h1><h2>W3C Working Draft <em>2 June 2011</em></h2><dl><dt>This Version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-animation-timing-20110602/">http://www.w3.org/TR/2011/WD-animation-timing-20110602/</a></dd><dt>Latest Version:</dt><dd><a href="http://www.w3.org/TR/animation-timing/">http://www.w3.org/TR/animation-timing/</a></dd><dt>Editors:</dt><dd><a href="http://webstuff.nfshost.com/">James Robinson</a>, Google, Inc &lt;jamesr@chromium.org&gt;</dd><dd><a href="http://mcc.id.au/">Cameron McCormack</a>, Mozilla Corporation &lt;cam@mcc.id.au&gt;</dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> &copy; 2011 <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>&reg;</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr />

<div class="section">
<h2>Abstract</h2>
<p>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.</p>
</div>

<div class="section">
<h2>Status of this Document</h2>

<p><em>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 <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
http://www.w3.org/TR/.</em></p><p>This document is the 2 June 2011 <b>First Public Working Draft</b> of the
  <cite>Timing control for script-based animations</cite> specification.

Please send comments about this document to
<a href="mailto:public-web-perf@w3.org?subject=[RequestAnimationFrame]%20">public-web-perf@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/public-web-perf/">archived</a>)
with <samp>[RequestAnimationFrame]</samp> at the start of the subject line.</p>

<p>This document is produced by
   the <a href="http://www.w3.org/2010/webperf/">Web Performance</a>
   Working Group. The Web Performance Working Group is part of
   the <a href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients
   Activity</a> in the
   W3C <a href="http://www.w3.org/Interaction/">Interaction
     Domain</a>.  Changes made to this document can be found in the
   <a href="https://dvcs.w3.org/hg/webperf/file/tip/specs/RequestAnimationFrame/">W3C
     public Mercurial server</a>.</p>

<p>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.</p><p>This document was produced by a group operating under the
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>.
W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/45211/status">public list of any patent disclosures</a> 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
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a>
must disclose the information in accordance with
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p>
</div>

<div id="toc">
<h2>Table of Contents</h2>
<div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#conformance">2. Conformance</a></li><li><a href="#definitions">3. Definitions</a></li><li><a href="#the-WindowAnimationTiming-interface">4. The WindowAnimationTiming interface</a></li><li><a href="#acknowledgements">5. Acknowledgements</a></li></ul><ul><li><a href="#references">A. References</a><ul><li><a href="#normative-references">A.1. Normative references</a></li><li><a href="#informative-references">A.2. Informative references</a></li></ul></li><li><a href="#changes">B. Changes</a></li></ul></div>
</div>

<div id="sections">

<div id="introduction" class="section">
<h2>1. Introduction</h2>

<p class="norm">This section is informative.</p>

<p>Animations in web browsers come in two forms: native, declarative ones, such
as the <code>&lt;animate&gt;</code> element in SVG, and those that are implemented
in script.  These script-based animations are most often performed by scheduling
a callback using <code>setTimeout</code> or <code>setInterval</code> and making
changes to the DOM to effect the animation in that callback.</p>

<p>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 <code>setTimeout</code> 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.</p>

<p>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.</p>

<div class="example"><div class="exampleHeader">Example</div>
  <p>Here is an example of using the API to write a script-based animation.</p>
  <div class="block"><div class="blockTitleDiv"><span class="blockTitle">HTML</span></div><div class="blockContent"><pre class="code html-code">&lt;!DOCTYPE html&gt;
&lt;title&gt;Script-based animation using requestAnimationFrame&lt;/title&gt;
&lt;style&gt;
div { position: absolute; left: 10px; padding: 50px;
  background: crimson; color: white }
&lt;/style&gt;
&lt;script&gt;
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.cancelRequestAnimationFrame(requestId);
  requestId = 0;
}
&lt;/script&gt;
&lt;button onclick="start()"&gt;Click me to start!&lt;/button&gt;
&lt;button onclick="stop()"&gt;Click me to stop!&lt;/button&gt;
&lt;div id="animated"&gt;Hello there.&lt;/div&gt;</pre></div></div>
</div>

</div>

<div id="conformance" class="section">
<h2>2. Conformance</h2>

<p>Everything in this specification is normative except for diagrams, examples,
notes and sections marked as being informative.</p>

<p>The keywords
“<span class="rfc2119">MUST</span>”,
“<span class="rfc2119">MUST NOT</span>”,
“<span class="rfc2119">REQUIRED</span>”,
“<span class="rfc2119">SHALL</span>”,
“<span class="rfc2119">SHALL NOT</span>”,
“<span class="rfc2119">SHOULD</span>”,
“<span class="rfc2119">SHOULD NOT</span>”,
“<span class="rfc2119">RECOMMENDED</span>”,
“<span class="rfc2119">MAY</span>” and
“<span class="rfc2119">OPTIONAL</span>” in this document are to be interpreted
as described in <cite><a href="http://www.ietf.org/rfc/rfc2119">Key words for
use in RFCs to Indicate Requirement Levels</a></cite>. <a href="#ref-RFC2119">[RFC2119]</a></p>

<p>The IDL fragment in <a href="#the-WindowAnimationTiming-interface">section 4</a>
of this specification <span class="rfc2119">MUST</span> be interpreted as required for
<a href="http://www.w3.org/TR/WebIDL/#dfn-conforming-idl-fragment">conforming IDL fragments</a>,
as described in the <a href="http://www.w3.org/TR/WebIDL/"><cite>Web IDL</cite></a> specification. <a href="#ref-WEBIDL">[WEBIDL]</a></p>

<p>This specification defines a single conformance class:</p>

<dl>
  <dt><dfn>conforming user agent</dfn></dt>
  <dd>A user agent is considered to be a conforming user agent if it
  satisfies all of the <span class="rfc2119">MUST</span>-,
  <span class="rfc2119">REQUIRED</span>- and
  <span class="rfc2119">SHALL</span>-level criteria in this specification.
  A conforming user agent <span class="rfc2119">MUST</span> also be a
  <a href="http://www.w3.org/TR/WebIDL/#dfn-conforming-implementation">conforming implementation</a>
  of the IDL fragment in <a href="#the-WindowAnimationTiming-interface">section 4</a>
  of this specification, as described in the
  <a href="http://www.w3.org/TR/WebIDL/"><cite>Web IDL</cite></a> specification. <a href="#ref-WEBIDL">[WEBIDL]</a></dd>
</dl>

<p>This specification references interfaces and types from a number of other
specifications:</p>

<ul>
  <li><code>Document</code> <a href="#ref-DOM3CORE">[DOM3CORE]</a></li>
  <li><code>Window</code> <a href="#ref-HTML5">[HTML5]</a></li>
  <li><code>DOMTimeStamp</code> <a href="#ref-WEBIDL">[WEBIDL]</a></li>
</ul>
</div>

<div id="definitions" class="section">
<h2>3. Definitions</h2>

<p>Associated with every <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>
is an <dfn id="dfn-animation-frame-request-callback-list">animation frame request callback list</dfn>,
which is a list of &lt;<var>handle</var>, <var>callback</var>, <var>cancelled</var>&gt; triples.
<var>handle</var> is an integer that uniquely identifies the entry in the list,
<var>callback</var> is a <code><a href="#FrameRequestCallback">FrameRequestCallback</a></code>
object, and <var>cancelled</var> is a Boolean flag.  Initially, the
<a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation frame request callback list</a>
for a <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>
is empty.</p>

<p>A <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>
is said to <dfn id="dfn-has-active-animations">have active animations</dfn>
whenever it has a non-empty <a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation
frame request callback list</a>.</p>

</div>

<div id="the-WindowAnimationTiming-interface" class="section">
<h2>4. The WindowAnimationTiming interface</h2>

<p>The <code><a href="#WindowAnimationTiming">WindowAnimationTiming</a></code> interface is used to expose the
<code><a href="#requestAnimationFrame">requestAnimationFrame</a></code>
operation on the <code><a href="http://www.w3.org/TR/html5/browsers.html#the-window-object">Window</a></code>
object.  In the definition of <code><a href="#requestAnimationFrame">requestAnimationFrame</a></code> below, references to the
<code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>
object are to be taken to be references to the <code><a href="http://www.w3.org/TR/html5/browsers.html#the-window-object">Window</a></code>
object’s <a href="http://www.w3.org/TR/html5/browsers.html#active-document">active document</a>. <a href="#ref-HTML5">[HTML5]</a></p>

<pre class="idl"><span class="xattr">[Supplemental, NoInterfaceObject]</span>
interface <dfn id="WindowAnimationTiming">WindowAnimationTiming</dfn> {
  long <a href="#requestAnimationFrame">requestAnimationFrame</a>(in <a href="#FrameRequestCallback">FrameRequestCallback</a> callback);
  void <a href="#cancelRequestAnimationFrame">cancelRequestAnimationFrame</a>(in long handle);
};

<a href="http://www.w3.org/TR/html5/browsers.html#the-window-object">Window</a> implements <a href="#WindowAnimationTiming">WindowAnimationTiming</a>;

<span class="xattr">[Callback, NoInterfaceObject]</span>
interface <dfn id="FrameRequestCallback">FrameRequestCallback</dfn> {
  void sample(in <a href="http://dev.w3.org/2006/webapi/WebIDL/#common-DOMTimeStamp">DOMTimeStamp</a> time);
};</pre>

<p>The <dfn id="requestAnimationFrame"><code>requestAnimationFrame</code></dfn> method is
used to signal to the user agent that a <!--a class='dfnref' href='#dfn-script-based-animation'-->script-based animation<!--/a-->
needs to be resampled.  When <code>requestAnimationFrame(<var>callback</var>)</code> is called, the user agent <span class="rfc2119">MUST</span> schedule a script-based animation
resampling by appending to the end of the <a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation frame request callback list</a>
an entry whose <var>handle</var> is a user-agent-defined integer greater than zero that uniquely identifies the entry in the list,
whose <var>callback</var> is <code><var>callback</var></code> and whose <var>cancelled</var> flag is false.</p>

<div class="note"><div class="noteHeader">Note</div>
  <p><code><a href="#requestAnimationFrame">requestAnimationFrame</a></code> only schedules
  a single update to the script-based animation.  If subsequent animation frames are needed, then
  <code><a href="#requestAnimationFrame">requestAnimationFrame</a></code> will need to be called
  again from within the callback.</p>

  <p>Also note that multiple calls to <code>requestAnimationFrame</code> with the same callback
  (before <a class="dfnref" href="#dfn-invoke-callbacks-algorithm">callbacks are invoked</a> 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.</p>
</div>

<div class="ednote"><div class="ednoteHeader">Editorial note</div>
  <p><a href="http://www.w3.org/2010/webperf/track/issues/4">ISSUE-4</a> Do we want to allow an <code>Element</code> to be passed
  to <code>requestAnimationFrame</code>, so that animations affecting the given element are throttled or paused when scrolled out
  of view?</p>
</div>

<p>The <dfn id="cancelRequestAnimationFrame"><code>cancelRequestAnimationFrame</code></dfn> method is
used to cancel a previously made request to schedule an animation frame update.  When <code>cancelRequestAnimationFrame(<var>handle</var>)</code> is called,
the user agent <span class="rfc2119">MUST</span> set the <var>cancelled</var> flag to true for the entry in the
<a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation frame request callback list</a>
whose <var>handle</var> is <code><var>handle</var></code>.  If there is no entry in the list with the given
handle, then this function does nothing.</p>

<div class="note"><div class="noteHeader">Note</div>
  <p><code><a href="#cancelRequestAnimationFrame">cancelRequestAnimationFrame</a></code> might be called for an entry
  in the <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>’s
  <a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation frame request callback list</a> or in
  the <a class="dfnref" href="#dfn-sample-all-animations">sample all animations</a> operation’s temporary <var>list</var>.  In
  either case the entry’s cancelled flag is set to true so that the callback does not run.</p>
</div>


<p>While a <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>
<a class="dfnref" href="#dfn-has-active-animations">has active animations</a>, the user agent
<span class="rfc2119">MUST</span> continually <dfn id="dfn-sample-all-animations">sample all animations</dfn>.
To <a class="dfnref" href="#dfn-sample-all-animations">sample all animations</a>, the following steps are performed:</p>

<div class="ednote"><div class="ednoteHeader">Editorial note</div>
  <p><a href="http://www.w3.org/2010/webperf/track/issues/1">ISSUE-1</a> We should define the processing model in terms of an HTML5 task queue, so that animation frame callback scheduling participates in the browser event loop in a well defined manner, rather than just saying that animations are sampled continually.</p>
</div>

<ol class="algorithm">
  <li>Let <var>t</var> be the result of <a class="dfnref" href="#dfn-get-next-sample-time">getting the next sample time</a>
    of the <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>.
    <div class="ednote"><div class="ednoteHeader">Editorial note</div>
      <p><a href="http://www.w3.org/2010/webperf/track/issues/2">ISSUE-2</a> <dfn id="dfn-get-next-sample-time">Getting the next sample time</dfn>
      is currently undefined.  This time should be the same as the time that contemporaneous native animations have been sampled at.</p>
    </div>
  </li>
  <li>Let <var>time</var> be <var>t</var> expressed as the number of milliseconds since 1970-01-01T00:00:00Z.
    <div class="ednote"><div class="ednoteHeader">Editorial note</div>
      <p><a href="http://www.w3.org/2010/webperf/track/issues/3">ISSUE-3</a> 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 <code>Window.animationStartTime</code> attribute that was present in an earlier
      draft, so that scripts can avoid using <code>Date.now()</code> to record the animation start time,
      which might bear little relation to the monotonic clock values anyway.</p>
    </div>
  </li>
  <li>Let <var>list</var> be a copy of the <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>’s
  <a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation frame request callback list</a>.  <var>list</var> will be empty
  if no <!--a class='dfnref' href='#dfn-script-based-animation'-->script-based animations<!--/a--> have been scheduled.</li>
  <li>Clear the <code><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#i-Document">Document</a></code>’s
  <a class="dfnref" href="#dfn-animation-frame-request-callback-list">animation frame request callback list</a>.</li>
  <li>Perform the steps defined in the <a class="dfnref" href="#dfn-invoke-callbacks-algorithm">invoke callbacks algorithm</a> with parameters <var>list</var> and <var>time</var></li>
</ol>

<p>The expectation is that the user agent will never run the
<a class="dfnref" href="#dfn-invoke-callbacks-algorithm">invoke callbacks algorithm</a> more than
once per display refresh, and that when there is no need to throttle down the animation sample rate,
it will attempt to run the <a class="dfnref" href="#dfn-invoke-callbacks-algorithm">invoke callbacks algorithm</a>
at exactly once per display refresh.</p>

<div class="ednote"><div class="ednoteHeader">Editorial note</div>
  <p><a href="http://www.w3.org/2010/webperf/track/issues/5">ISSUE-5</a> Do we need to set expectations on exactly how rate throttling is done, and if callback invocation can be suspended indefinitely?</p>
</div>

<p>The <dfn id="dfn-invoke-callbacks-algorithm">invoke callbacks algorithm</dfn>:</p>
<ol class="algorithm">
  <li>For each entry <var>callback</var> in <var>list</var>, in order:
    <ol>
      <li>If the cancelled flag on <var>callback</var> is not true:
        <ol>
          <li>Call the <code><a href="#FrameRequestCallback">sample</a></code> operation of <var>callback</var> with <var>time</var> as the argument.</li>
          <li>If calling the operation resulted in an exception being thrown, then catch that exception and ignore it.</li>
        </ol>
      </li>
    </ol>
  </li>
</ol>
</div>

<div id="acknowledgements" class="section">
<h2>5. Acknowledgements</h2>

<p class="norm">This section is informative.</p>

<p>The editors would like to thank the following people for contributing to
this specification: Boris Zbarsky, Jonas Sicking, Robert O’Callahan.</p>
</div>

</div> <!-- sections -->

<div id="appendices">

<div id="references" class="section">
<h2>A. References</h2>

<div id="normative-references" class="section">
<h3>A.1. Normative references</h3>

<dl>
  <dt id="ref-DOM3CORE">[DOM3CORE]</dt>
  <dd><cite><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/">Document Object Model (DOM) Level 3 Core Specification</a></cite>.
  A. Le Hors, et al., Editors.  World Wide Web Consortium, April 2004.  Available at http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/.</dd>
  <dt id="ref-HTML5">[HTML5]</dt>
  <dd><cite><a href="http://www.w3.org/TR/2010/WD-html5-20100624/">HTML5</a></cite>.
  I. Hickson, Editor.
  World Wide Web Consortium, June 2010.
  Available at http://www.w3.org/TR/2010/WD-html5-20100624/.</dd>
  <dt id="ref-RFC2119">[RFC2119]</dt>
  <dd><cite><a href="http://www.ietf.org/rfc/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></cite>,
  S. Bradner.  IETF, March 1997.  Available at http://www.ietf.org/rfc/rfc2119.</dd>
  <dt id="ref-WEBIDL">[WEBIDL]</dt>
  <dd><cite><a href="http://www.w3.org/TR/2010/WD-WebIDL-20101021/">Web IDL</a></cite>.
  C. McCormack, Editor.
  World Wide Web Consortium, October 2010.
  Available at http://www.w3.org/TR/2010/WD-WebIDL-20101021/.</dd>
</dl>
</div>

<div id="informative-references" class="section">
  <h3>A.2. Informative references</h3>

  <ul>
    <li><p>This specification was written based on the <code><a href="https://developer.mozilla.org/en/DOM/window.mozRequestAnimationFrame">mozRequestAnimationFrame</a></code>
    feature implemented in Firefox.</p></li>
  </ul>
</div>

</div> <!-- references -->

<div id="changes" class="section">
<h2>B. Changes</h2>

<p>The following is a list of substantial changes to the document on each publication.</p>

<dl class="changes">
  <!--
  <dt>Current editor’s draft</dt>
  <dd>...</dd>
  -->
  <dt>2 June 2011 – FPWD</dt>
  <dd>
    <ul>
      <li>Initial publication.</li>
    </ul>
  </dd>
</dl>
</div>

</div> <!-- appendices -->

</body>
</html>