specs/RequestAnimationFrame/Overview.xml
author Philippe Le Hegaret <plh@w3.org>
Wed, 22 Feb 2012 17:16:49 -0500
changeset 402 843f6eb989ba
parent 399 5c257806b290
child 409 829c4d9bb1a8
permissions -rw-r--r--
Fixed HTML5 ref
jamesr@194
     1
<?xml version='1.0'?>
jamesr@194
     2
jamesr@194
     3
<!--
jamesr@194
     4
  Overview.xml
jamesr@194
     5
  Timing control for script-based animations
jamesr@194
     6
jamesr@194
     7
  This is written in XHTML 1.0 Strict with an inline <options> element that
jamesr@213
     8
  helps the RequestAnimationFrame.xsl stylesheet process the document (generating a table
jamesr@194
     9
  of contents, section numbers, certain processing instructions).
jamesr@194
    10
  -->
jamesr@194
    11
jamesr@213
    12
<?xml-stylesheet href='RequestAnimationFrame.xsl' type='text/xsl'?>
jamesr@194
    13
jamesr@194
    14
<html xmlns='http://www.w3.org/1999/xhtml' xmlns:x='http://mcc.id.au/ns/local' xml:lang='en'>
jamesr@194
    15
<head>
jamesr@194
    16
  <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
jamesr@194
    17
  <title>Timing control for script-based animations</title>
jamesr@213
    18
  <link rel='stylesheet' href='RequestAnimationFrame.css' type='text/css'/>
jamesr@194
    19
  <script src='section-links.js' type='application/ecmascript'/>
jamesr@194
    20
  <script src='dfn.js' type='application/ecmascript'/>
jamesr@194
    21
jamesr@194
    22
  <options xmlns='http://mcc.id.au/ns/local'>
jamesr@194
    23
    <versions>
cam@273
    24
      <this href='http://www.w3.org/TR/2011/WD-animation-timing-20110602/'/>
jamesr@213
    25
      <draft href='http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/RequestAnimationFrame/Overview.html'/>
cam@273
    26
      <latest href='http://www.w3.org/TR/animation-timing/'/>
jamesr@194
    27
    </versions>
jamesr@194
    28
    <editors>
jamesr@194
    29
      <person homepage='http://webstuff.nfshost.com/' email='jamesr@chromium.org'>
jamesr@194
    30
        <name>James Robinson</name>
jamesr@194
    31
        <affiliation>Google, Inc</affiliation>
jamesr@194
    32
      </person>
jamesr@194
    33
      <person homepage='http://mcc.id.au/' email='cam@mcc.id.au'>
jamesr@194
    34
        <name>Cameron McCormack</name>
jamesr@194
    35
        <affiliation>Mozilla Corporation</affiliation>
jamesr@194
    36
      </person>
jamesr@194
    37
    </editors>
cam@270
    38
    <maturity>ED</maturity>
jamesr@194
    39
  </options>
jamesr@194
    40
</head>
jamesr@194
    41
jamesr@194
    42
<body>
jamesr@194
    43
<?top?>
jamesr@194
    44
jamesr@194
    45
<div class='section'>
jamesr@194
    46
<h2>Abstract</h2>
jamesr@194
    47
<p>This document defines an API web page authors can use to write script-based
jamesr@194
    48
animations where the user agent is in control of limiting the update
jamesr@194
    49
rate of the animation.  The user agent is in a better position to determine
jamesr@194
    50
the ideal animation rate based on whether the page is currently in a foreground
jamesr@194
    51
or background tab, what the current load on the CPU is, and so on.  Using this
jamesr@194
    52
API should therefore result in more appropriate utilization of the CPU
jamesr@194
    53
by the browser.</p>
jamesr@194
    54
</div>
jamesr@194
    55
jamesr@194
    56
<div class='section'>
jamesr@194
    57
<h2>Status of this Document</h2>
jamesr@194
    58
cam@258
    59
<?sotd-top public-web-perf@w3.org http://lists.w3.org/Archives/Public/public-web-perf/ [RequestAnimationFrame]?>
jamesr@194
    60
jamesr@194
    61
<p>This document is produced by
jamesr@194
    62
   the <a href="http://www.w3.org/2010/webperf/">Web Performance</a>
jamesr@194
    63
   Working Group. The Web Performance Working Group is part of
jamesr@194
    64
   the <a href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients
jamesr@194
    65
   Activity</a> in the
jamesr@194
    66
   W3C <a href="http://www.w3.org/Interaction/">Interaction
cam@258
    67
     Domain</a>.  Changes made to this document can be found in the
cam@262
    68
   <a href='https://dvcs.w3.org/hg/webperf/file/tip/specs/RequestAnimationFrame/'>W3C
cam@258
    69
     public Mercurial server</a>.</p>
jamesr@194
    70
cam@258
    71
<?sotd-bottom http://www.w3.org/2004/01/pp-impl/45211/status?>
jamesr@194
    72
</div>
jamesr@194
    73
jamesr@194
    74
<div id='toc'>
jamesr@194
    75
<h2>Table of Contents</h2>
jamesr@194
    76
<?toc sections appendices?>
jamesr@194
    77
</div>
jamesr@194
    78
jamesr@194
    79
<div id='sections'>
jamesr@194
    80
jamesr@194
    81
<div id='introduction' class='section'>
jamesr@194
    82
<h2>Introduction</h2>
jamesr@194
    83
jamesr@194
    84
<p class='norm'>This section is informative.</p>
jamesr@194
    85
jamesr@194
    86
<p>Animations in web browsers come in two forms: native, declarative ones, such
jamesr@194
    87
as the <code>&lt;animate></code> element in SVG, and those that are implemented
jamesr@194
    88
in script.  These script-based animations are most often performed by scheduling
jamesr@194
    89
a callback using <code>setTimeout</code> or <code>setInterval</code> and making
jamesr@194
    90
changes to the DOM to effect the animation in that callback.</p>
jamesr@194
    91
jamesr@194
    92
<p>A disadvantage of this approach is that the author of the animation script has
jamesr@194
    93
no idea what the ideal frequency for updating their animation is.  Instead, the
jamesr@194
    94
easiest way forward for the author is to simply call <code>setTimeout</code> with
jamesr@194
    95
a very small value, which in practice will be clamped to some minimum time like
jamesr@194
    96
10ms anyway.  It likely won’t be the case that 100 updates per second are required
jamesr@194
    97
for the animation, especially if the page is in a background tab or the browser
jamesr@194
    98
window is minimized.</p>
jamesr@194
    99
jamesr@194
   100
<p>The API described in this document allows script authors to request the user
jamesr@194
   101
agent schedule an animation frame update.  The user agent is in a better position
jamesr@194
   102
to determine how many frames per second to allocate to all of the animations running
jamesr@194
   103
in the entire browser.  If there are many animations active, the user agent can
jamesr@194
   104
select a frame rate such that all of the animations will run as smoothly as possible.
jamesr@194
   105
If the page is not currently visible, animations on that page can be throttled
jamesr@194
   106
heavily so that they do not update often and thus consume little CPU power.</p>
jamesr@194
   107
jamesr@194
   108
<div class='example'>
jamesr@194
   109
  <p>Here is an example of using the API to write a script-based animation.</p>
jamesr@194
   110
  <x:codeblock language='html'><![CDATA[<!DOCTYPE html>
cam@250
   111
<title>Script-based animation using requestAnimationFrame</title>
cam@250
   112
<style>
cam@252
   113
div { position: absolute; left: 10px; padding: 50px;
cam@252
   114
  background: crimson; color: white }
cam@250
   115
</style>
cam@250
   116
<script>
cam@250
   117
var requestId = 0;
jamesr@194
   118
cam@250
   119
function animate(time) {
cam@252
   120
  document.getElementById("animated").style.left =
cam@252
   121
    (time - animationStartTime) % 2000 / 4 + "px";
cam@250
   122
  requestId = window.requestAnimationFrame(animate);
cam@250
   123
}
cam@250
   124
function start() {
cam@250
   125
  animationStartTime = Date.now();
cam@250
   126
  requestId = window.requestAnimationFrame(animate);
cam@250
   127
}
cam@250
   128
function stop() {
cam@250
   129
  if (requestId)
jamesr@368
   130
    window.cancelAnimationFrame(requestId);
cam@250
   131
  requestId = 0;
cam@250
   132
}
cam@250
   133
</script>
cam@252
   134
<button onclick="start()">Click me to start!</button>
cam@252
   135
<button onclick="stop()">Click me to stop!</button>
cam@252
   136
<div id="animated">Hello there.</div>]]></x:codeblock>
jamesr@194
   137
</div>
jamesr@194
   138
jamesr@194
   139
</div>
jamesr@194
   140
jamesr@194
   141
<div id='conformance' class='section'>
jamesr@194
   142
<h2>Conformance</h2>
jamesr@194
   143
jamesr@194
   144
<p>Everything in this specification is normative except for diagrams, examples,
jamesr@194
   145
notes and sections marked as being informative.</p>
jamesr@194
   146
jamesr@194
   147
<p>The keywords
jamesr@194
   148
“<span class='rfc2119'>MUST</span>”,
jamesr@194
   149
“<span class='rfc2119'>MUST NOT</span>”,
jamesr@194
   150
“<span class='rfc2119'>REQUIRED</span>”,
jamesr@194
   151
“<span class='rfc2119'>SHALL</span>”,
jamesr@194
   152
“<span class='rfc2119'>SHALL NOT</span>”,
jamesr@194
   153
“<span class='rfc2119'>SHOULD</span>”,
jamesr@194
   154
“<span class='rfc2119'>SHOULD NOT</span>”,
jamesr@194
   155
“<span class='rfc2119'>RECOMMENDED</span>”,
jamesr@194
   156
“<span class='rfc2119'>MAY</span>” and
jamesr@194
   157
“<span class='rfc2119'>OPTIONAL</span>” in this document are to be interpreted
jamesr@194
   158
as described in <cite><a href='http://www.ietf.org/rfc/rfc2119'>Key words for
jamesr@194
   159
use in RFCs to Indicate Requirement Levels</a></cite>.&#x2002;<a href='#ref-RFC2119'>[RFC2119]</a></p>
jamesr@194
   160
jamesr@194
   161
<p>The IDL fragment in <a href='#the-WindowAnimationTiming-interface'>section <?sref the-WindowAnimationTiming-interface?></a>
jamesr@194
   162
of this specification <span class='rfc2119'>MUST</span> be interpreted as required for
jamesr@194
   163
<a href='http://www.w3.org/TR/WebIDL/#dfn-conforming-idl-fragment'>conforming IDL fragments</a>,
jamesr@194
   164
as described in the <a href='http://www.w3.org/TR/WebIDL/'><cite>Web IDL</cite></a> specification.&#x2002;<a href='#ref-WEBIDL'>[WEBIDL]</a></p>
jamesr@194
   165
jamesr@194
   166
<p>This specification defines a single conformance class:</p>
jamesr@194
   167
jamesr@194
   168
<dl>
jamesr@194
   169
  <dt><dfn>conforming user agent</dfn></dt>
jamesr@194
   170
  <dd>A user agent is considered to be a conforming user agent if it
jamesr@194
   171
  satisfies all of the <span class='rfc2119'>MUST</span>-,
jamesr@194
   172
  <span class='rfc2119'>REQUIRED</span>- and
jamesr@194
   173
  <span class='rfc2119'>SHALL</span>-level criteria in this specification.
jamesr@194
   174
  A conforming user agent <span class='rfc2119'>MUST</span> also be a
jamesr@194
   175
  <a href='http://www.w3.org/TR/WebIDL/#dfn-conforming-implementation'>conforming implementation</a>
jamesr@194
   176
  of the IDL fragment in <a href='#the-WindowAnimationTiming-interface'>section <?sref the-WindowAnimationTiming-interface?></a>
jamesr@194
   177
  of this specification, as described in the
jamesr@194
   178
  <a href='http://www.w3.org/TR/WebIDL/'><cite>Web IDL</cite></a> specification.&#x2002;<a href='#ref-WEBIDL'>[WEBIDL]</a></dd>
jamesr@194
   179
</dl>
jamesr@194
   180
jamesr@194
   181
<p>This specification references interfaces and types from a number of other
jamesr@194
   182
specifications:</p>
jamesr@194
   183
jamesr@194
   184
<ul>
plh@399
   185
  <li><code>Document</code>&#x2002;<a href='#ref-DOM4'>[DOM4]</a></li>
jamesr@194
   186
  <li><code>Window</code>&#x2002;<a href='#ref-HTML5'>[HTML5]</a></li>
jamesr@194
   187
  <li><code>DOMTimeStamp</code>&#x2002;<a href='#ref-WEBIDL'>[WEBIDL]</a></li>
jamesr@194
   188
</ul>
jamesr@194
   189
</div>
jamesr@194
   190
jamesr@194
   191
<div id='definitions' class='section'>
jamesr@194
   192
<h2>Definitions</h2>
jamesr@194
   193
plh@399
   194
<p>Associated with every <code><a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a></code>
cam@253
   195
is an <dfn id='dfn-animation-frame-request-callback-list'>animation frame request callback list</dfn>,
jamesr@369
   196
which is a list of &lt;<var>handle</var>, <var>callback</var>&gt; tuples.
jamesr@369
   197
<var>handle</var> is an integer that uniquely identifies the entry in the list.
cam@253
   198
<var>callback</var> is a <code><a href='#FrameRequestCallback'>FrameRequestCallback</a></code>
jamesr@369
   199
object.  Initially, the
cam@253
   200
<a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a>
plh@399
   201
for a <code><a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a></code>
cam@253
   202
is empty.</p>
jamesr@194
   203
plh@399
   204
<p>A <code><a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a></code>
cam@256
   205
is said to <dfn id='dfn-has-active-animations'>have active animations</dfn>
cam@256
   206
whenever it has a non-empty <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation
cam@256
   207
frame request callback list</a>.</p>
cam@256
   208
jamesr@194
   209
</div>
jamesr@194
   210
jamesr@194
   211
<div id='the-WindowAnimationTiming-interface' class='section'>
jamesr@194
   212
<h2>The WindowAnimationTiming interface</h2>
jamesr@194
   213
jamesr@194
   214
<p>The <code><a href='#WindowAnimationTiming'>WindowAnimationTiming</a></code> interface is used to expose the
jamesr@194
   215
<code><a href='#requestAnimationFrame'>requestAnimationFrame</a></code>
jamesr@194
   216
operation on the <code><a href='http://www.w3.org/TR/html5/browsers.html#the-window-object'>Window</a></code>
jamesr@194
   217
object.  In the definition of <code><a href='#requestAnimationFrame'>requestAnimationFrame</a></code> below, references to the
plh@399
   218
<code><a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a></code>
jamesr@194
   219
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>
jamesr@369
   220
object’s <a href='http://www.w3.org/TR/html5/browsers.html#active-document'>active document</a>. <a href='#ref-HTML5'>[HTML5]</a></p>
jamesr@194
   221
cam@382
   222
<pre class='idl'><span class='xattr'>[NoInterfaceObject]</span>
jamesr@194
   223
interface <dfn id='WindowAnimationTiming'>WindowAnimationTiming</dfn> {
cam@382
   224
  long <a href='#requestAnimationFrame'>requestAnimationFrame</a>(<a href='#FrameRequestCallback'>FrameRequestCallback</a> callback);
cam@382
   225
  void <a href='#cancelAnimationFrame'>cancelAnimationFrame</a>(long handle);
jamesr@194
   226
};
jamesr@194
   227
jamesr@194
   228
<a href='http://www.w3.org/TR/html5/browsers.html#the-window-object'>Window</a> implements <a href='#WindowAnimationTiming'>WindowAnimationTiming</a>;
jamesr@194
   229
cam@382
   230
callback <dfn id='FrameRequestCallback'>FrameRequestCallback</dfn> = void (<a href='http://www.w3.org/TR/WebIDL/#common-DOMTimeStamp'>DOMTimeStamp</a> time);</pre>
jamesr@194
   231
jamesr@194
   232
<p>The <dfn id='requestAnimationFrame'><code>requestAnimationFrame</code></dfn> method is
jamesr@369
   233
used to signal to the user agent that a script-based animation
jamesr@201
   234
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
cam@253
   235
resampling by appending to the end of the <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a>
jamesr@369
   236
an entry whose <var>handle</var> is a user-agent-defined integer greater than zero that uniquely identifies the entry in the list and
jamesr@369
   237
whose <var>callback</var> is <code><var>callback</var></code>.</p>
jamesr@369
   238
plh@399
   239
<p>Each <a class='dfnref' href='#FrameRequestCallback'>FrameRequestCallback</a> object has a <dfn id='callbackCancelledFlag'>cancelled</dfn> boolean flag. This
jamesr@369
   240
flag is initially false and is not exposed by any interface.</p>
jamesr@194
   241
jamesr@194
   242
<div class='note'>
jamesr@194
   243
  <p><code><a href='#requestAnimationFrame'>requestAnimationFrame</a></code> only schedules
jamesr@194
   244
  a single update to the script-based animation.  If subsequent animation frames are needed, then
jamesr@194
   245
  <code><a href='#requestAnimationFrame'>requestAnimationFrame</a></code> will need to be called
jamesr@194
   246
  again from within the callback.</p>
cam@254
   247
cam@254
   248
  <p>Also note that multiple calls to <code>requestAnimationFrame</code> with the same callback
cam@254
   249
  (before <a class='dfnref' href='#dfn-invoke-callbacks-algorithm'>callbacks are invoked</a> and
cam@254
   250
  the list is cleared) will result in multiple entries being in the list with that same callback,
cam@254
   251
  and thus will result in that callback being invoked more than once for the animation frame.</p>
jamesr@194
   252
</div>
jamesr@194
   253
cam@253
   254
<div class='ednote'>
cam@253
   255
  <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
cam@253
   256
  to <code>requestAnimationFrame</code>, so that animations affecting the given element are throttled or paused when scrolled out
cam@253
   257
  of view?</p>
cam@253
   258
</div>
cam@253
   259
jamesr@368
   260
<p>The <dfn id='cancelAnimationFrame'><code>cancelAnimationFrame</code></dfn> method is
jamesr@368
   261
used to cancel a previously made request to schedule an animation frame update.  When <code>cancelAnimationFrame(<var>handle</var>)</code> is called,
plh@399
   262
the user agent <span class='rfc2119'>MUST</span> set the <a class='dfnref' href='#callbackCancelledFlag'>cancelled</a> flag to true for the
plh@399
   263
<a class='dfnref' href='#dfn-animation-frame-request-callback'>callback</a> registered on this <a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a> whose <var>handle</var> is <code><var>handle</var></code>. The cancelled
jamesr@369
   264
flag is set whether the callback is in a <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a> or not.
jamesr@373
   265
If there is no callback with the given handle, then this function does nothing.</p>
jamesr@201
   266
jamesr@201
   267
<div class='note'>
jamesr@368
   268
  <p><code><a href='#cancelAnimationFrame'>cancelAnimationFrame</a></code> might be called for an entry
plh@399
   269
  in the <code><a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a></code>’s
jamesr@201
   270
  <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a> or in
cam@253
   271
  the <a class='dfnref' href="#dfn-sample-all-animations">sample all animations</a> operation’s temporary <var>list</var>.  In
cam@253
   272
  either case the entry’s cancelled flag is set to true so that the callback does not run.</p>
jamesr@201
   273
</div>
jamesr@201
   274
cam@253
   275
</div>
cam@253
   276
jamesr@307
   277
<div id='processingmodel' class='section'>
jamesr@307
   278
<h2>Processing Model</h2>
plh@399
   279
Whenever a <a class='dfnref' href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a>'s
plh@399
   280
<a class='dfnref' href='http://www.w3.org/TR/page-visibility/#pv-hidden'>hidden</a> attribute is false
jamesr@307
   281
and the <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a> is not empty, the user agent MUST
plh@399
   282
regularly <a class='dfnref' href='http://www.w3.org/TR/html5/webappapis.html#queue-a-task'>queue</a> a <a class='dfnref' href='http://www.w3.org/TR/html5/webappapis.html#concept-task'>task</a> that
jamesr@370
   283
<a class='dfnref' href='#dfn-sample-all-animations'>samples all animations</a> for that
plh@399
   284
<a class='dfnref' href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a>'s
plh@399
   285
<a class='dfnref' href='http://www.w3.org/TR/html5/browsers.html#top-level-browsing-context'>top-level browsing context</a>.
plh@399
   286
The <a class='dfnref' href='http://www.w3.org/TR/html5/webappapis.html#task-source'>task source</a>
plh@399
   287
for these <a class='dfnref' href='http://www.w3.org/TR/html5/webappapis.html#concept-task'>tasks</a> is the <dfn id='dfn-animation-task-source'>animation task source</dfn>. Only one
plh@399
   288
task should be generated per <a class='dfnref' href='http://www.w3.org/TR/html5/browsers.html#top-level-browsing-context'>top-level browsing context</a>, even if multiple
plh@399
   289
<a class='dfnref' href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#document'>Document</a>s within the same
plh@399
   290
<a class='dfnref' href='http://www.w3.org/TR/html5/browsers.html#top-level-browsing-context'>top-level browsing context</a> are not hidden and contain callbacks.
jamesr@307
   291
jamesr@307
   292
To <dfn id='dfn-sample-all-animations'>samples all animations</dfn> , the following steps are performed:
jamesr@194
   293
<ol class='algorithm'>
jamesr@194
   294
  <li>Let <var>t</var> be the result of <a class='dfnref' href='#dfn-get-next-sample-time'>getting the next sample time</a>
plh@399
   295
    of the <a class='dfnref' href='http://www.w3.org/TR/html5/browsers.html#top-level-browsing-context'>top-level browsing context</a>.
cam@253
   296
    <div class='ednote'>
cam@261
   297
      <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>
cam@261
   298
      is currently undefined.  This time should be the same as the time that contemporaneous native animations have been sampled at.</p>
cam@253
   299
    </div>
cam@253
   300
  </li>
cam@253
   301
  <li>Let <var>time</var> be <var>t</var> expressed as the number of milliseconds since 1970-01-01T00:00:00Z.
cam@253
   302
    <div class='ednote'>
cam@253
   303
      <p><a href="http://www.w3.org/2010/webperf/track/issues/3">ISSUE-3</a> Having animation frame times run off a
cam@253
   304
      monotonic clock that increases at a constant rate would be better for authors than using the wallclock time
cam@253
   305
      as reported by the system, which might jump backwards or move forwards at varying rates due to clock slew.
cam@253
   306
      Doing this argues for the reinclusion of the <code>Window.animationStartTime</code> attribute that was present in an earlier
cam@253
   307
      draft, so that scripts can avoid using <code>Date.now()</code> to record the animation start time,
cam@253
   308
      which might bear little relation to the monotonic clock values anyway.</p>
cam@253
   309
    </div>
cam@253
   310
  </li>
jamesr@370
   311
  <li>Let <var>list</var> be an empty <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a>.</li>
plh@399
   312
  <li>Let <var>contexts</var> be the results of <a class='dfnref' href='http://www.w3.org/TR/html5/browsers.html#list-of-the-descendant-browsing-contexts'>list of the descendant browsing contexts</a> algorithm for this task's top-level browsing context.</li>
jamesr@370
   313
  <li>For every <var>context</var> in <var>contexts</var>, in any order, perform the following steps:
jamesr@370
   314
    <ol>
plh@399
   315
      <li>Let <var>d</var> be <var>context</var>'s <a class='dfnref' href='http://www.w3.org/TR/html5/browsers.html#active-document'>active document</a>.</li>
plh@399
   316
      <li>If <var>d</var>'s <a class='dfnref' href='http://www.w3.org/TR/page-visibility/#pv-hidden'>hidden</a>
jamesr@370
   317
        attribute is true, continue to the next entry in the <var>contexts</var> list. Otherwise proceed with these steps.</li>
jamesr@370
   318
      <li>Let <var>doclist</var> be <var>d</var>'s <a class='dfnref' href='#dfn-animation-frame-request-callback-list'>animation frame request callback list</a>.</li>
jamesr@370
   319
      <li>Append all entries from <var>doclist</var> into <var>list</var> preserving order.</li>
jamesr@370
   320
      <li>Clear <var>doclist</var>.</li>
jamesr@370
   321
    </ol>
jamesr@370
   322
  </li>
jamesr@194
   323
  <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>
jamesr@194
   324
</ol>
cam@253
   325
jamesr@194
   326
<p>The <dfn id='dfn-invoke-callbacks-algorithm'>invoke callbacks algorithm</dfn>:</p>
jamesr@194
   327
<ol class='algorithm'>
jamesr@194
   328
  <li>For each entry <var>callback</var> in <var>list</var>, in order:
jamesr@194
   329
    <ol>
cam@260
   330
      <li>If the cancelled flag on <var>callback</var> is not true:
cam@260
   331
        <ol>
cam@382
   332
          <li>Call <var>callback</var> with <var>time</var> as the argument.</li>
cam@260
   333
          <li>If calling the operation resulted in an exception being thrown, then catch that exception and ignore it.</li>
cam@260
   334
        </ol>
cam@260
   335
      </li>
jamesr@194
   336
    </ol>
jamesr@194
   337
  </li>
jamesr@194
   338
</ol>
jamesr@307
   339
cam@382
   340
<div class='note'>
cam@382
   341
<p>
jamesr@307
   342
The expectation is that the user agent will run tasks from the <a class='dfnref' href='#dfn-animation-task-source'>animation task source</a> at
jamesr@307
   343
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
jamesr@307
   344
at a higher rate can cause extra computation to occur without a user-visible benefit.
jamesr@307
   345
</p>
jamesr@194
   346
</div>
jamesr@194
   347
cam@382
   348
</div>
cam@382
   349
jamesr@194
   350
<div id='acknowledgements' class='section'>
jamesr@194
   351
<h2>Acknowledgements</h2>
jamesr@194
   352
jamesr@194
   353
<p class='norm'>This section is informative.</p>
jamesr@194
   354
cam@251
   355
<p>The editors would like to thank the following people for contributing to
cam@253
   356
this specification: Boris Zbarsky, Jonas Sicking, Robert O’Callahan.</p>
plh@399
   357
plh@399
   358
plh@399
   359
<p>This specification was written based on the <code><a href="https://developer.mozilla.org/en/DOM/window.mozRequestAnimationFrame">mozRequestAnimationFrame</a></code>
plh@399
   360
    feature implemented in Firefox.</p>
jamesr@194
   361
</div>
jamesr@194
   362
jamesr@194
   363
</div> <!-- sections -->
jamesr@194
   364
jamesr@194
   365
<div id='appendices'>
jamesr@194
   366
jamesr@194
   367
<div id='references' class='section'>
jamesr@194
   368
<h2>References</h2>
jamesr@194
   369
jamesr@194
   370
<div id='normative-references' class='section'>
jamesr@194
   371
<h3>Normative references</h3>
jamesr@194
   372
jamesr@194
   373
<dl>
plh@399
   374
  <dt id='ref-DOM4'>[DOM4]</dt>
plh@399
   375
  <dd><cite><a href='http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html'>DOM4</a></cite>.
plh@399
   376
  Anne van Kesteren, Aryeh Gregor, and Ms2ger, Editors.  World Wide Web Consortium, January 2012.  Available at http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html.</dd>
plh@402
   377
  <dt>[<a id="ref-HTML5">HTML5</a>]</dt>
plh@402
   378
  <dd><cite><a href="http://www.w3.org/TR/html5/">HTML5</a></cite>, Ian Hickson, Editor. World Wide Web Consortium, May 2011. This version of the HTML5 is available from <a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a>. The <a href="http://dev.w3.org/html5/spec/">latest editor's draft</a> is available at http://dev.w3.org/html5/spec/.</dd>
jamesr@194
   379
  <dt id='ref-RFC2119'>[RFC2119]</dt>
jamesr@194
   380
  <dd><cite><a href='http://www.ietf.org/rfc/rfc2119'>Key words for use in RFCs to Indicate Requirement Levels</a></cite>,
jamesr@194
   381
  S. Bradner.  IETF, March 1997.  Available at http://www.ietf.org/rfc/rfc2119.</dd>
jamesr@194
   382
  <dt id='ref-WEBIDL'>[WEBIDL]</dt>
jamesr@307
   383
  <dd><cite><a href='http://www.w3.org/TR/WebIDL/'>Web IDL</a></cite>.
jamesr@194
   384
  C. McCormack, Editor.
jamesr@307
   385
  World Wide Web Consortium, July 2011.
jamesr@307
   386
  Available at http://www.w3.org/TR/WebIDL/.</dd>
jamesr@194
   387
</dl>
jamesr@194
   388
</div>
jamesr@194
   389
jamesr@194
   390
</div> <!-- references -->
jamesr@194
   391
jamesr@194
   392
<div id='changes' class='section'>
jamesr@194
   393
<h2>Changes</h2>
jamesr@194
   394
jamesr@194
   395
<p>The following is a list of substantial changes to the document on each publication.</p>
jamesr@194
   396
jamesr@194
   397
<dl class='changes'>
jamesr@194
   398
  <dt>Current editor’s draft</dt>
cam@270
   399
  <dd>
cam@270
   400
    <ul>
cam@277
   401
      ...
cam@270
   402
    </ul>
cam@270
   403
  </dd>
cam@256
   404
  <dt>2 June 2011 – FPWD</dt>
jamesr@194
   405
  <dd>
jamesr@194
   406
    <ul>
jamesr@194
   407
      <li>Initial publication.</li>
jamesr@194
   408
    </ul>
jamesr@194
   409
  </dd>
jamesr@194
   410
</dl>
jamesr@194
   411
</div>
jamesr@194
   412
jamesr@194
   413
</div> <!-- appendices -->
jamesr@194
   414
jamesr@194
   415
</body>
jamesr@194
   416
</html>