forked from WICG/frame-timing
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
234 lines (229 loc) · 14.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
<!DOCTYPE html>
<html>
<head>
<title>Frame Timing</title>
<meta charset='utf-8'>
<script src='//www.w3.org/Tools/respec/respec-w3c-common'
async class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "frame-timing",
edDraftURI: "https://w3c.github.io/frame-timing/",
editors: [
{
name: "Michael Blain"
, url: "http://github.org/mpb"
, mailto: "[email protected]"
, company: "Google"
, companyURL: "http://google.com/"
, w3cid: "73819"
},
{
name: "Ilya Grigorik"
, url: "https://www.igvita.com/"
, mailto: "[email protected]"
, company: "Google"
, companyURL: "https://google.com/"
, w3cid: "56102"
},
],
wg: "Web Performance Working Group",
wgURI: "http://www.w3.org/2010/webperf/",
wgPublicList: "public-web-perf",
subjectPrefix: "[Frame Timing]",
otherLinks: [{
key: 'Repository',
data: [{
value: 'We are on Github.',
href: 'https://github.com/w3c/frame-timing/'
}, {
value: 'File a bug.',
href: 'https://github.com/w3c/frame-timing/issues'
}, {
value: 'Commit history.',
href: 'https://github.com/w3c/frame-timing/commits/gh-pages/index.html'
}]
}],
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/45211/status",
};
</script>
</head>
<body>
<section id='abstract'>
<p>
This specification defines an interface to help web developers measure the performance of their applications by giving them access to frame performance data to facilitate smoothness (i.e. Frames per Second and Time to Frame) measurements.
</p>
</section>
<section id='sotd'>
<p>
This is a <strong>work in progress</strong> and may change without any notices.
</p>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [[ECMA-262]] provides a mechanism to approximate application Frames per Second (<dfn>FPS</dfn>) and Time to Frame (<dfn>TTF</dfn>) (by calling a nearly empty <code>requestAnimationFrame</code> [[Animation-Timing]] in a loop), the precision of this method has a high variance. Some example situations where this returns misleading results are:
<ul>
<li>
CSS Animations, which can be done off of the main thread and may not impact <code>requestAnimationFrame</code>
</li>
<li>
Scrolling, which can also be handled mostly off of the main thread, and may not impact <code>requestAnimationFrame</code>
</li>
<li>
Slow page loading (such as extensive DOM manipulation), which may consume a lot of time on the rendering thread and allow the main thread to fire a <code>requestAnimationFrame</code> event even though the new content has not yet been displayed to the user.
</li>
</ul>
</p>
<p>
This document defines the <a href="#performancerendertiming"><code>PerformanceRenderTiming</code></a> and <a href="#performancecompositetiming"><code>PerformanceCompositeTiming</code></a> interfaces, and extensions to the <a href="#extensions-performance-interface"><code>Performance</code></a> interface, which expose frame performance data to be used for smoothness measurements.
</p>
</section>
<section id="conformance">
<p>
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm.
</p>
<p>
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
</p>
<p>
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
</p>
<p>
The IDL fragments in this specification MUST be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [[!WebIDL]]
</p>
</section>
<section>
<h2>Terminology</h2>
<p>
The construction "a <code>Foo</code> object", where <code>Foo</code> is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".
</p>
<p>
The term "JavaScript" is used to refer to ECMAScript [[ECMA-262]], rather than the official term ECMAScript, since the term JavaScript is more widely known.
</p>
</section>
<section>
<h2>Frame Timing</h2>
<p>
</p>
<section class='informative'>
<h2>Introduction</h2>
<p>The <a>PerformanceRenderTiming</a> and <a>PerformanceCompositeTiming</a> interfaces, and extensions to the <a href="#extensions-performance-interface">Performance interface</a>, enable web developers to measure the performance of their applications by giving them access to frame performance data to facilitate smoothness (i.e. <a>FPS</a> and <a>TTF</a>) measurements:</p>
<ul>
<li><a>PerformanceRenderTiming</a> captures the work performed by the renderer to process the frame: DOM modification, JavaScript execution, CSS calculation, and similar activities.</li>
<li><a>PerformanceCompositeTiming</a> captures events performed by the compositor to place rendered content onto the screen.</li>
</ul>
<p>The relationship between <a>PerformanceRenderTiming</a> and <a>PerformanceCompositeTiming</a> events will vary based on the workload, and architecture and configuration of the user agent. For example, the user agent may report many <a>PerformanceCompositeTiming</a> events corresponding to a single <a>PerformanceRenderTiming</a> event due to a CSS animation, composite thread scrolling, or similar activities. Other workloads may result in 1:1 mapping of <a>PerformanceRenderTiming</a> and <a>PerformanceCompositeTiming</a> events, and the exact relationship is also subject to user agent architecture and configuration.</p>
</section>
<section id='extensions-performance-interface'>
<h2>Extensions to the <code>Performance</code> Interface</h2>
<p>
<dl title='partial interface Performance' class="idl">
<dt>void clearFrameTimings()</dt>
<dd>
The method <code>clearFrameTimings</code> clears the buffer used to store the current list of <a href="#performancerendertiming">PerformanceRenderTiming</a> resources.
</dd>
<dt>void setFrameTimingBufferSize()</dt>
<dd>
<dl class='parameters'>
<dt>unsigned long maxSize</dt>
<dd>
The maxSize parameter sets the maximum number of <a href="#performancerendertiming">PerformanceRenderTiming</a> resources that will be stored in the buffer.
</dd>
</dl>
The <code>setFrameTimingBufferSize</code> method, when invoked, MUST set the maximum number of <a href="#performancerendertiming">PerformanceRenderTiming</a> resources that may be stored in the buffer to the value of the <code>maxSize</code> parameter.
</dd>
<dt>attribute EventHandler onframetimingbufferfull</dt>
<dd>
The event handler for the <code>frametimingbufferfull</code> event. Immediately after the buffer used to store the list of <a href="#performancerendertiming">PerformanceRenderTiming</a> and <a href="#performancecompositetiming">PerformanceCompositeTiming</a>
resources becomes full, the User Agent MUST <a href='http://www.w3.org/TR/dom/#concept-event-fire'>fire a simple event</a> named <code>frametimingbufferfull</code> that bubbles, isn't cancelable, has no default action, at the
<a href="http://www.w3.org/TR/navigation-timing-2/#performance">Performance</a> object [[!Navigation-Timing-2]].
</dd>
</dl>
</p>
</section>
<section id='performancerendertiming'>
<h2>The <code>PerformanceRenderTiming</code> Interface</h2>
<p>
The <a>PerformanceRenderTiming</a> interface participates in the <a href="http://www.w3.org/TR/performance-timeline/#sec-performance-timeline">Performance Timeline</a> and extends the following attributes of the <a href="http://www.w3.org/TR/performance-timeline/#performanceentry">PerformanceEntry</a> interface [[!Performance-Timeline]]:
</p>
<dl class='attributes'>
<dt id='widl-PerformanceRenderTiming-name'><code>name</code></dt>
<dd>
This attribute MUST return the name of the requesting document.
</dd>
<dt id='widl-PerformanceRenderTiming-entryType'><code>entryType</code></dt>
<dd>
This attribute MUST return the <a href="http://www.w3.org/TR/WebIDL/#idl-DOMString"><code>DOMString</code></a> "<code>render</code>".
</dd>
<dt id='widl-PerformanceRenderTiming-startTime'><code>startTime</code></dt>
<dd>
This attribute MUST return a <a href="http://www.w3.org/TR/hr-time/#domhighrestimestamp"><code>DOMHighResTimeStamp</code></a> with current frame's beginning time value, which is the time that the <code>requestAnimationFrame</code> callback (see [[!Animation-Timing]]) would have fired for the frame. [[!HR-Time]].</p>
</dd>
<dt id='widl-PerformanceRenderTiming-duration'><code>duration</code></dt>
<dd>
This attribute MUST return a <a href="http://www.w3.org/TR/hr-time/#domhighrestimestamp"><code>DOMHighResTimeStamp</code></a> with the difference between the end of the frame and the <code>startTime</code> of the frame. The end of the frame is defined as what the beginning time of the next frame's <code>requestAnimationFrame</code> callback (see [[!Animation-Timing]]) would have been, had one been scheduled in the current frame. If a <code>requestAnimationFrame</code> is already requested, its beginning time SHOULD be used.
</dd>
</dl>
<dl title='interface PerformanceRenderTiming : <a href="http://www.w3.org/TR/performance-timeline/#performanceentry">PerformanceEntry</a>' class='idl'>
<dt>readonly attribute unsigned long sourceFrameNumber</dt>
<dd>
This attribute MUST return the source frame number for the event. This is used to correlate <code>PerformanceRenderTiming</code> and <code>PerformanceCompositeTiming</code> events to measure time-to-frame delays.
</dd>
<dt>serializer = { inherit, attribute }</dt>
</dl>
</p>
</section>
<section id='performancecompositetiming'>
<h2>The <code>PerformanceCompositeTiming</code> Interface</h2>
<p>
The <a>PerformanceCompositeTiming</a> interface participates in the <a href="http://www.w3.org/TR/performance-timeline/#sec-performance-timeline">Performance Timeline</a> and extends the following attributes of the <a href="http://www.w3.org/TR/performance-timeline/#performanceentry">PerformanceEntry</a> interface [[!Performance-Timeline]]:
</p>
<dl class='attributes'>
<dt id='widl-PerformanceCompositeTiming-name'><code>name</code></dt>
<dd>
This attribute MUST return the name of the requesting document.
</dd>
<dt id='widl-PerformanceCompositeTiming-entryType'><code>entryType</code></dt>
<dd>
This attribute MUST return the <a href="http://www.w3.org/TR/WebIDL/#idl-DOMString"><code>DOMString</code></a> "<code>composite</code>".
</dd>
<dt id='widl-PerformanceCompositeTiming-startTime'><code>startTime</code></dt>
<dd>
This attribute MUST return a <a href="http://www.w3.org/TR/hr-time/#domhighrestimestamp"><code>DOMHighResTimeStamp</code></a> with the event's time value [[!HR-Time]].
</dd>
<dt id='widl-PerformanceCompositeTiming-duration'><code>duration</code></dt>
<dd>
The <code>duration</code> attribute MUST return a <a href="http://www.w3.org/TR/hr-time/#domhighrestimestamp"><code>DOMHighResTimeStamp</code></a> of value 0.
</dd>
</dl>
<dl title='interface PerformanceCompositeTiming : <a href="http://www.w3.org/TR/performance-timeline/#performanceentry">PerformanceEntry</a>' class='idl'>
<dt>readonly attribute unsigned long sourceFrameNumber</dt>
<dd>
This attribute MUST return the last known source frame number for the event. This is used to correlate <code>PerformanceRenderTiming</code> and <code>PerformanceCompositeTiming</code> events to measure time-to-frame delays.
</dd>
<dt>serializer = { inherit, attribute }</dt>
</dl>
</section>
</section>
<section>
<h2>Monotonic Clock</h2>
<p>
The time values stored within the interface MUST monotonically increase to ensure they are not affected by adjustments to the system clock. The difference between any two chronologically recorded time values MUST never be negative. The user agent MUST record the system clock at the beginning of the navigation and define subsequent time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.
</p>
</section>
<section class='informative'>
<h2>Privacy and Security</h2>
<p>
The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. However, unlike other interfaces defined in the Performance Timeline, the interfaces defined in this specification do not have any restrictions on sharing timing information through script. This is because the web platform has been designed with the invariant that any script included on a page has the same access as any other script included on that page regardless of the origin of the script.
</p>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
Thanks to Enne Walker, Rick Byers and Chris Harrelson for their helpful comments.
</p>
</section>
</body>
</html>