Skip to content

Commit 43657f3

Browse files
authored
[web] Add frame number support. (#171592)
Fixes flutter/flutter#170972 ### Description - Adds `frameData` with `frameNumber` value to `FrameService` - Adds non-mock `frameData` to `EngineFlutterWindow` and `EnginePlatformDispatcher` - Adds `frameNumber` value to `FrameTimingRecorder`'s recorded timings ## Pre-launch Checklist - [X] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [X] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [X] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [X] I signed the [CLA]. - [X] I listed at least one issue that this PR fixes in the description above. - [X] I updated/added relevant documentation (doc comments with `///`). - [X] I added new tests to check the change I am making, or this PR is [test-exempt]. - [X] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [X] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 8f34ca2 commit 43657f3

8 files changed

Lines changed: 182 additions & 26 deletions

File tree

‎engine/src/flutter/lib/web_ui/lib/src/engine/frame_service.dart‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -36,18 +36,16 @@ class FrameService {
3636
_instance = mock;
3737
}
3838

39-
/// A monotonically increasing frame number being rendered.
40-
///
41-
/// This is intended for tests only.
42-
int get debugFrameNumber => _debugFrameNumber;
43-
int _debugFrameNumber = 0;
39+
/// The [ui.FrameData] object for the current frame.
40+
ui.FrameData get frameData => _frameData;
41+
ui.FrameData _frameData = const ui.FrameData();
4442

45-
/// Resets [debugFrameNumber] back to zero.
43+
/// Resets [frameData] back to the initial value.
4644
///
4745
/// This is intended for tests only.
4846
@visibleForTesting
49-
void debugResetFrameNumber() {
50-
_debugFrameNumber = 0;
47+
void debugResetFrameData() {
48+
_frameData = const ui.FrameData();
5149
}
5250

5351
/// Whether a frame has already been scheduled.
@@ -102,7 +100,7 @@ class FrameService {
102100

103101
try {
104102
_isRenderingFrame = true;
105-
_debugFrameNumber += 1;
103+
_frameData = ui.FrameData(frameNumber: _frameData.frameNumber + 1);
106104
_renderFrame(highResTime.toDartDouble);
107105
} finally {
108106
_isRenderingFrame = false;
@@ -132,7 +130,7 @@ class FrameService {
132130

133131
Timer.run(() {
134132
_isRenderingFrame = true;
135-
_debugFrameNumber += 1;
133+
_frameData = ui.FrameData(frameNumber: _frameData.frameNumber + 1);
136134
// TODO(yjbanov): it's funky that if beginFrame crashes, the drawFrame
137135
// fires anyway. We should clean this up, or better explain
138136
// what the expectations are for various situations. The
@@ -158,6 +156,7 @@ class FrameService {
158156
}
159157

160158
void _renderFrame(double highResTime) {
159+
FrameTimingRecorder.recordCurrentFrameNumber(_frameData.frameNumber);
161160
FrameTimingRecorder.recordCurrentFrameVsync();
162161

163162
// In Flutter terminology "building a frame" consists of "beginning
@@ -181,6 +180,10 @@ class FrameService {
181180
);
182181
}
183182

183+
if (EnginePlatformDispatcher.instance.onFrameDataChanged != null) {
184+
EnginePlatformDispatcher.instance.invokeOnFrameDataChanged();
185+
}
186+
184187
if (EnginePlatformDispatcher.instance.onDrawFrame != null) {
185188
// On mobile Flutter flushes microtasks between onBeginFrame and
186189
// onDrawFrame. The web doesn't because there's no way to hook into the

‎engine/src/flutter/lib/web_ui/lib/src/engine/frame_timing_recorder.dart‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@
22
// Use of this source code is governed by a BSD-style license that can be
33
// found in the LICENSE file.
44

5+
import 'package:meta/meta.dart';
56
import 'package:ui/src/engine.dart';
67
import 'package:ui/ui.dart' as ui;
78

89
class FrameTimingRecorder {
10+
final int _frameNumber = _currentFrameNumber;
911
final int _vsyncStartMicros = _currentFrameVsyncStart;
1012
final int _buildStartMicros = _currentFrameBuildStart;
1113

@@ -18,12 +20,30 @@ class FrameTimingRecorder {
1820
/// This list is periodically reported to the framework (see [_kFrameTimingsSubmitInterval]).
1921
static List<ui.FrameTiming> _frameTimings = <ui.FrameTiming>[];
2022

21-
/// These two metrics are collected early in the process, before the respective
23+
/// List of the collected frame timings that are not yet reported.
24+
///
25+
/// This is intended for tests only.
26+
@visibleForTesting
27+
static List<ui.FrameTiming> get debugFrameTimings => _frameTimings;
28+
29+
@visibleForTesting
30+
static void debugResetFrameTimings() {
31+
_frameTimings = <ui.FrameTiming>[];
32+
}
33+
34+
/// These three metrics are collected early in the process, before the respective
2235
/// scene builders are created. These are instead treated as global state, which
2336
/// are used to initialize any recorders that are created by the scene builders.
37+
static int _currentFrameNumber = 0;
2438
static int _currentFrameVsyncStart = 0;
2539
static int _currentFrameBuildStart = 0;
2640

41+
static void recordCurrentFrameNumber(int frameNumber) {
42+
if (frameTimingsEnabled) {
43+
_currentFrameNumber = frameNumber;
44+
}
45+
}
46+
2747
static void recordCurrentFrameVsync() {
2848
if (frameTimingsEnabled) {
2949
_currentFrameVsyncStart = _nowMicros();
@@ -36,6 +56,21 @@ class FrameTimingRecorder {
3656
}
3757
}
3858

59+
@visibleForTesting
60+
static void debugResetCurrentFrameNumber() {
61+
_currentFrameNumber = 0;
62+
}
63+
64+
@visibleForTesting
65+
static void debugResetCurrentFrameVsync() {
66+
_currentFrameVsyncStart = 0;
67+
}
68+
69+
@visibleForTesting
70+
static void debugResetCurrentFrameBuildStart() {
71+
_currentFrameBuildStart = 0;
72+
}
73+
3974
/// The last time (in microseconds) we submitted frame timings.
4075
static int _frameTimingsLastSubmitTime = _nowMicros();
4176

@@ -87,6 +122,7 @@ class FrameTimingRecorder {
87122
rasterStart: _rasterStartMicros!,
88123
rasterFinish: _rasterFinishMicros!,
89124
rasterFinishWallTime: _rasterFinishMicros!,
125+
frameNumber: _frameNumber,
90126
);
91127
_frameTimings.add(timing);
92128
final int now = _nowMicros();

‎engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher.dart‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1292,8 +1292,26 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
12921292
});
12931293
}
12941294

1295+
/// The [ui.FrameData] object for the current frame.
12951296
@override
1296-
ui.FrameData get frameData => const ui.FrameData.webOnly();
1297+
ui.FrameData get frameData => FrameService.instance.frameData;
1298+
1299+
/// A callback that is invoked when the window updates the [ui.FrameData].
1300+
@override
1301+
ui.VoidCallback? get onFrameDataChanged => _onFrameDataChanged;
1302+
ui.VoidCallback? _onFrameDataChanged;
1303+
Zone _onFrameDataChangedZone = Zone.root;
1304+
@override
1305+
set onFrameDataChanged(ui.VoidCallback? callback) {
1306+
_onFrameDataChanged = callback;
1307+
_onFrameDataChangedZone = Zone.current;
1308+
}
1309+
1310+
/// Engine code should use this method instead of the callback directly.
1311+
/// Otherwise zones won't work properly.
1312+
void invokeOnFrameDataChanged() {
1313+
invoke(onFrameDataChanged, _onFrameDataChangedZone);
1314+
}
12971315

12981316
@override
12991317
double scaleFontSize(double unscaledFontSize) => unscaledFontSize * textScaleFactor;

‎engine/src/flutter/lib/web_ui/lib/src/engine/window.dart‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -475,12 +475,14 @@ final class EngineFlutterWindow extends EngineFlutterView implements ui.Singleto
475475
}
476476

477477
@override
478-
ui.FrameData get frameData => const ui.FrameData.webOnly();
478+
ui.FrameData get frameData => platformDispatcher.frameData;
479479

480480
@override
481-
ui.VoidCallback? get onFrameDataChanged => null;
481+
ui.VoidCallback? get onFrameDataChanged => platformDispatcher.onFrameDataChanged;
482482
@override
483-
set onFrameDataChanged(ui.VoidCallback? callback) {}
483+
set onFrameDataChanged(ui.VoidCallback? callback) {
484+
platformDispatcher.onFrameDataChanged = callback;
485+
}
484486

485487
@override
486488
ui.AccessibilityFeatures get accessibilityFeatures => platformDispatcher.accessibilityFeatures;

‎engine/src/flutter/lib/web_ui/lib/window.dart‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -165,9 +165,15 @@ abstract final class IsolateNameServer {
165165
SingletonFlutterWindow get window => engine.window;
166166

167167
class FrameData {
168-
const FrameData.webOnly();
169-
170-
int get frameNumber => -1;
168+
const FrameData({this.frameNumber = 0});
169+
170+
/// The number of the current frame.
171+
///
172+
/// This number monotonically increases, but doesn't necessarily
173+
/// start at a particular value.
174+
///
175+
/// If not provided, defaults to 0.
176+
final int frameNumber;
171177
}
172178

173179
class GestureSettings {

‎engine/src/flutter/lib/web_ui/test/engine/frame_service_test.dart‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,22 +34,22 @@ void testMain() {
3434

3535
test('counts frames', () async {
3636
final instance = FrameService.instance;
37-
instance.debugResetFrameNumber();
37+
instance.debugResetFrameData();
3838

3939
final frameCompleter = Completer<void>();
4040
instance.onFinishedRenderingFrame = () {
4141
frameCompleter.complete();
4242
};
4343

44-
expect(instance.debugFrameNumber, 0);
44+
expect(instance.frameData.frameNumber, 0);
4545
instance.scheduleFrame();
4646
await frameCompleter.future;
47-
expect(instance.debugFrameNumber, 1);
47+
expect(instance.frameData.frameNumber, 1);
4848
});
4949

50-
test('isFrameScheduled is true iff the frame is scheduled', () async {
50+
test('isFrameScheduled is true if the frame is scheduled', () async {
5151
final instance = FrameService.instance;
52-
instance.debugResetFrameNumber();
52+
instance.debugResetFrameData();
5353

5454
var frameCompleter = Completer<void>();
5555
instance.onFinishedRenderingFrame = () {
@@ -62,10 +62,10 @@ void testMain() {
6262
expect(instance.isFrameScheduled, isTrue);
6363
await frameCompleter.future;
6464
expect(instance.isFrameScheduled, isFalse);
65-
expect(instance.debugFrameNumber, 1);
65+
expect(instance.frameData.frameNumber, 1);
6666

6767
// Test idempotency
68-
instance.debugResetFrameNumber();
68+
instance.debugResetFrameData();
6969
frameCompleter = Completer<void>();
7070
instance.scheduleFrame();
7171
instance.scheduleFrame();
@@ -75,7 +75,7 @@ void testMain() {
7575
expect(instance.isFrameScheduled, isTrue);
7676
await frameCompleter.future;
7777
expect(instance.isFrameScheduled, isFalse);
78-
expect(instance.debugFrameNumber, 1);
78+
expect(instance.frameData.frameNumber, 1);
7979
});
8080

8181
test('onBeginFrame and onDrawFrame are called with isRenderingFrame set to true', () async {
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// Copyright 2013 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:test/bootstrap/browser.dart';
6+
import 'package:test/test.dart';
7+
import 'package:ui/src/engine.dart';
8+
import 'package:ui/ui.dart' as ui;
9+
10+
void main() {
11+
internalBootstrapBrowserTest(() => testMain);
12+
}
13+
14+
void testMain() {
15+
group('FrameTimingRecorder', () {
16+
setUp(() {
17+
EnginePlatformDispatcher.instance.onReportTimings = null;
18+
FrameTimingRecorder.debugResetCurrentFrameNumber();
19+
FrameTimingRecorder.debugResetCurrentFrameVsync();
20+
FrameTimingRecorder.debugResetCurrentFrameBuildStart();
21+
FrameTimingRecorder.debugResetFrameTimings();
22+
});
23+
24+
tearDown(() {
25+
EnginePlatformDispatcher.instance.onReportTimings = null;
26+
FrameTimingRecorder.debugResetCurrentFrameNumber();
27+
FrameTimingRecorder.debugResetCurrentFrameVsync();
28+
FrameTimingRecorder.debugResetCurrentFrameBuildStart();
29+
FrameTimingRecorder.debugResetFrameTimings();
30+
});
31+
32+
test('frameTimingsEnabled is false when onReportTimings is not set', () {
33+
expect(EnginePlatformDispatcher.instance.onReportTimings, isNull);
34+
expect(FrameTimingRecorder.frameTimingsEnabled, isFalse);
35+
});
36+
37+
test('frameTimingsEnabled is true when onReportTimings is set', () {
38+
EnginePlatformDispatcher.instance.onReportTimings = (_) {};
39+
expect(EnginePlatformDispatcher.instance.onReportTimings, isNotNull);
40+
expect(FrameTimingRecorder.frameTimingsEnabled, isTrue);
41+
});
42+
43+
test('uses recorded frame number', () {
44+
EnginePlatformDispatcher.instance.onReportTimings = (_) {};
45+
expect(FrameTimingRecorder.frameTimingsEnabled, isTrue);
46+
47+
const int frameNumber1 = 333;
48+
FrameTimingRecorder.recordCurrentFrameNumber(frameNumber1);
49+
50+
FrameTimingRecorder()
51+
..recordBuildFinish()
52+
..recordRasterStart()
53+
..recordRasterFinish()
54+
..submitTimings();
55+
56+
expect(FrameTimingRecorder.debugFrameTimings.length, 1);
57+
final ui.FrameTiming timing1 = FrameTimingRecorder.debugFrameTimings.first;
58+
expect(timing1.frameNumber, frameNumber1);
59+
60+
const int frameNumber2 = 334;
61+
FrameTimingRecorder.recordCurrentFrameNumber(frameNumber2);
62+
63+
FrameTimingRecorder()
64+
..recordBuildFinish()
65+
..recordRasterStart()
66+
..recordRasterFinish()
67+
..submitTimings();
68+
69+
expect(FrameTimingRecorder.debugFrameTimings.length, 2);
70+
final ui.FrameTiming timing2 = FrameTimingRecorder.debugFrameTimings.last;
71+
expect(timing2.frameNumber, frameNumber2);
72+
});
73+
});
74+
}

‎engine/src/flutter/lib/web_ui/test/engine/window_test.dart‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,23 @@ Future<void> testMain() async {
396396
expect(responded, isTrue);
397397
});
398398

399+
test('onFrameDataChanged preserves the zone', () {
400+
final Zone innerZone = Zone.current.fork();
401+
402+
innerZone.runGuarded(() {
403+
void callback() {
404+
expect(Zone.current, innerZone);
405+
}
406+
407+
myWindow.onFrameDataChanged = callback;
408+
409+
// Test that the getter returns the exact same callback, e.g. it doesn't wrap it.
410+
expect(myWindow.onFrameDataChanged, same(callback));
411+
});
412+
413+
EnginePlatformDispatcher.instance.invokeOnFrameDataChanged();
414+
});
415+
399416
// Emulates the framework sending a request for screen orientation lock.
400417
Future<bool> sendSetPreferredOrientations(List<dynamic> orientations) {
401418
final Completer<bool> completer = Completer<bool>();

0 commit comments

Comments
 (0)