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