Skip to content

Commit def08f4

Browse files
Yusufihsangorgelharryterkelsenflutter-zl
authored
Wait for web rendering before first-frame event (flutter#189500)
The `flutter-first-frame` browser event currently fires as soon as the framework sends the `flutter/service_worker` platform message. Web scene rendering is asynchronous, so the event can remove an HTML splash while SkWasm is still rasterizing and briefly expose a blank frame. This change tracks scene renders that are still in progress, waits for them, and dispatches the event on the next browser animation frame. The tests cover both the asynchronous browser-event contract and an explicitly gated scene render, so the latter proves that the event cannot overtake rasterization. Fixes flutter#189499. ## Validation - `felt test --gcs-prod --browser chrome test/engine/window_test.dart test/ui/async_rendering_test.dart` passed in all seven selected suites: - dart2js / CanvasKit (Chromium and full variants) - dart2wasm / CanvasKit - dart2wasm / SkWasm (threaded and forced single-threaded) - dart2wasm / Wimp - `dart analyze` reported no issues for the implementation and both test files. - A minimal SkWasm reproduction exposed a blank compositor frame after the event in 3/3 cold runs before this change. The first visible Flutter frame followed the event by 90.3–143.0 ms. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [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 `///`), or this change does not alter public API documentation. - [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 this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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 --------- Co-authored-by: Harry Terkelsen <[email protected]> Co-authored-by: zhongliugo <[email protected]>
1 parent 0d95c36 commit def08f4

3 files changed

Lines changed: 254 additions & 17 deletions

File tree

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

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,33 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
5858

5959
final Arena frameArena = Arena();
6060

61+
/// The number of renders requested by the first frame that have not settled
62+
/// yet.
63+
///
64+
/// A multi-view app renders one scene per view, so the first frame is not
65+
/// settled until all of them are. A render whose scene is superseded by a
66+
/// newer one counts as settled, because the view will display the newer scene
67+
/// instead.
68+
int _pendingFirstFrameRenders = 0;
69+
70+
/// Whether the first frame is still being built, and can therefore still
71+
/// request renders.
72+
///
73+
/// This is false for the rest of the app's lifetime once the first frame ends,
74+
/// so renders requested by later frames are not counted, even while the first
75+
/// frame's own renders are still in flight.
76+
bool _isBuildingFirstFrame = true;
77+
78+
/// Completes once every render the first frame requested has settled, and is
79+
/// then set to null to stop tracking renders for the rest of the app's
80+
/// lifetime.
81+
///
82+
/// The framework reports its first frame from a post-frame callback, while web
83+
/// renderers may still be rasterizing that frame asynchronously. The browser
84+
/// event waits on this so it is not sent while the first frame is still
85+
/// rasterizing.
86+
Completer<void>? _firstFrameCompleter = Completer<void>();
87+
6188
/// The [EnginePlatformDispatcher] singleton.
6289
static EnginePlatformDispatcher get instance => _instance;
6390
static final EnginePlatformDispatcher _instance = EnginePlatformDispatcher();
@@ -274,6 +301,13 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
274301
invoke(_onDrawFrame, _onDrawFrameZone);
275302
_viewsRenderedInCurrentFrame = null;
276303
frameArena.collect();
304+
if (_isBuildingFirstFrame) {
305+
// The first frame has requested every render it is ever going to request.
306+
// A frame that rendered nothing is still a first frame, so there may be
307+
// nothing left to wait for.
308+
_isBuildingFirstFrame = false;
309+
_completeFirstFrameIfRendered();
310+
}
277311
}
278312

279313
/// A callback that is invoked when pointer data is available.
@@ -563,7 +597,7 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
563597

564598
// Dispatched by the bindings to delay service worker initialization.
565599
case 'flutter/service_worker':
566-
domWindow.dispatchEvent(createDomEvent('Event', 'flutter-first-frame'));
600+
unawaited(_dispatchFirstFrameEventAfterRender());
567601
return;
568602

569603
case 'flutter/textinput':
@@ -756,8 +790,44 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
756790
// view hasn't been rendered already in this scope.
757791
final bool shouldRender = _viewsRenderedInCurrentFrame?.add(target) ?? false;
758792
if (shouldRender) {
759-
await renderer.renderScene(scene, target);
793+
final Future<void> sceneRender = renderer.renderScene(scene, target);
794+
// The first frame ends while this render is still in flight, so remember
795+
// whether it belongs to it instead of asking again below.
796+
final bool isFirstFrameRender = _isBuildingFirstFrame;
797+
if (isFirstFrameRender) {
798+
_pendingFirstFrameRenders++;
799+
}
800+
try {
801+
await sceneRender;
802+
} finally {
803+
if (isFirstFrameRender) {
804+
_pendingFirstFrameRenders--;
805+
_completeFirstFrameIfRendered();
806+
}
807+
}
808+
}
809+
}
810+
811+
/// Completes [_firstFrameCompleter] once the first frame is done building and
812+
/// every render it requested has settled.
813+
///
814+
/// A render that failed counts as settled: [render] reports the failure to
815+
/// its caller, and withholding the browser event would leave an app that hides
816+
/// its loading screen on that event stuck on it forever.
817+
void _completeFirstFrameIfRendered() {
818+
if (_isBuildingFirstFrame || _pendingFirstFrameRenders > 0) {
819+
return;
760820
}
821+
_firstFrameCompleter?.complete();
822+
// Null it out to completely disable tracking for all future frames.
823+
_firstFrameCompleter = null;
824+
}
825+
826+
Future<void> _dispatchFirstFrameEventAfterRender() async {
827+
await _firstFrameCompleter?.future;
828+
domWindow.requestAnimationFrame((_) {
829+
domWindow.dispatchEvent(createDomEvent('Event', 'flutter-first-frame'));
830+
});
761831
}
762832

763833
@override

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

Lines changed: 38 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -546,23 +546,46 @@ void testMain() {
546546
expect(localeChangedCount, 1);
547547
});
548548

549-
test('dispatches browser event on flutter/service_worker channel', () async {
550-
final completer = Completer<void>();
551-
domWindow.addEventListener(
552-
'flutter-first-frame',
553-
createDomEventListener((DomEvent e) => completer.complete()),
554-
);
555-
final Zone innerZone = Zone.current.fork();
549+
test('dispatches browser event asynchronously on flutter/service_worker channel', () async {
550+
// Each dispatcher tracks its own first frame, and only the first one. The
551+
// singleton's is already over by now, because previous tests pump frames on
552+
// it, so this test brings its own dispatcher, like 'registration' below, to
553+
// make the frame it pumps really the first one.
554+
final ownDispatcher = EnginePlatformDispatcher();
555+
addTearDown(ownDispatcher.dispose);
556+
557+
var eventCount = 0;
558+
final DomEventListener listener = createDomEventListener((DomEvent e) => eventCount++);
559+
domWindow.addEventListener('flutter-first-frame', listener);
560+
addTearDown(() => domWindow.removeEventListener('flutter-first-frame', listener));
561+
562+
// The event is dispatched from an animation frame callback, so an animation
563+
// frame is long enough to observe one that was sent.
564+
Future<void> awaitAnimationFrame() {
565+
final completer = Completer<void>();
566+
domWindow.requestAnimationFrame((_) => Timer.run(completer.complete));
567+
return completer.future;
568+
}
556569

557-
innerZone.runGuarded(() {
558-
myWindow.sendPlatformMessage(
559-
'flutter/service_worker',
560-
ByteData(0),
561-
(ByteData? outputData) {},
562-
);
563-
});
570+
ownDispatcher.sendPlatformMessage(
571+
'flutter/service_worker',
572+
ByteData(0),
573+
(ByteData? outputData) {},
574+
);
564575

565-
await expectLater(completer.future, completes);
576+
// The event waits for the first frame to be on screen, which hasn't happened
577+
// yet.
578+
await awaitAnimationFrame();
579+
expect(eventCount, 0);
580+
581+
// This frame renders no scene, but a first frame that rendered nothing is
582+
// still a first frame, so ending it releases the event with nothing left to
583+
// wait for. Ending the frame resolves what the dispatch is waiting on
584+
// synchronously, so the dispatch is queued from a microtask, which runs
585+
// before the animation frame below.
586+
ownDispatcher.invokeOnDrawFrame();
587+
await awaitAnimationFrame();
588+
expect(eventCount, 1);
566589
});
567590

568591
test('sets global html attributes', () {

‎engine/src/flutter/lib/web_ui/test/ui/async_rendering_test.dart‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
// found in the LICENSE file.
44

55
import 'dart:async';
6+
import 'dart:typed_data';
67

78
import 'package:test/bootstrap/browser.dart';
89
import 'package:test/test.dart';
@@ -89,6 +90,149 @@ void testMain() {
8990
printWarning = originalPrintWarning;
9091
});
9192

93+
test('first-frame browser event waits for the first frame to be rendered', () async {
94+
// Each dispatcher tracks only its own first frame, so this test brings its
95+
// own and drives its `onDrawFrame` directly, instead of going through the
96+
// singleton via `renderScene`, to stay independent of what ran before it.
97+
final ownDispatcher = EnginePlatformDispatcher();
98+
addTearDown(ownDispatcher.dispose);
99+
100+
final EngineFlutterView view = EnginePlatformDispatcher.instance.implicitView!;
101+
final displayFactory = DisplayCanvasFactory<DisplayCanvas>(
102+
createCanvas: () => FakeDisplayCanvas(),
103+
);
104+
final testRasterizer = TestRasterizer(view, displayFactory)
105+
..prepareCompleter = Completer<void>();
106+
final ViewRasterizer originalRasterizer = renderer.rasterizers[view.viewId]!;
107+
renderer.rasterizers[view.viewId] = testRasterizer;
108+
addTearDown(() => renderer.rasterizers[view.viewId] = originalRasterizer);
109+
110+
var firstFrameEventCount = 0;
111+
final firstFrameEvent = Completer<void>();
112+
final DomEventListener listener = createDomEventListener((DomEvent event) {
113+
firstFrameEventCount++;
114+
if (!firstFrameEvent.isCompleted) {
115+
firstFrameEvent.complete();
116+
}
117+
});
118+
domWindow.addEventListener('flutter-first-frame', listener);
119+
addTearDown(() => domWindow.removeEventListener('flutter-first-frame', listener));
120+
121+
// Wait for next frame.
122+
Future<void> waitForAnimationFrame() {
123+
final completer = Completer<void>();
124+
domWindow.requestAnimationFrame((_) {
125+
Timer.run(completer.complete);
126+
});
127+
return completer.future;
128+
}
129+
130+
// `render` only draws anything in an `onDrawFrame` scope, so a frame is a
131+
// scene rendered from within `onDrawFrame`.
132+
Future<void> renderFrame() {
133+
final ui.Scene scene = ui.SceneBuilder().build();
134+
addTearDown(scene.dispose);
135+
late final Future<void> rendered;
136+
ownDispatcher.onDrawFrame = () {
137+
rendered = ownDispatcher.render(scene, view);
138+
};
139+
ownDispatcher.invokeOnDrawFrame();
140+
return rendered;
141+
}
142+
143+
final Future<void> renderFuture = renderFrame();
144+
ownDispatcher.sendPlatformMessage(
145+
'flutter/service_worker',
146+
ByteData(0),
147+
(ByteData? response) {},
148+
);
149+
150+
// The render is parked in `prepareToDraw`, so nothing is on screen yet. The
151+
// event is dispatched from an animation frame callback, so waiting for one
152+
// is enough to observe it if it were sent too early.
153+
await waitForAnimationFrame();
154+
expect(firstFrameEventCount, 0);
155+
156+
testRasterizer.prepareCompleter!.complete();
157+
await renderFuture;
158+
await expectLater(firstFrameEvent.future, completes);
159+
160+
// Renders requested by later frames are not tracked, and don't dispatch the
161+
// event again, no matter how many frames go by.
162+
await renderFrame();
163+
await waitForAnimationFrame();
164+
expect(firstFrameEventCount, 1);
165+
166+
await renderFrame();
167+
await waitForAnimationFrame();
168+
expect(firstFrameEventCount, 1);
169+
});
170+
171+
test('first-frame browser event is still sent if a first-frame render fails', () async {
172+
// Each dispatcher tracks only its own first frame, so this test brings its
173+
// own and drives its `onDrawFrame` directly instead of going through
174+
// `renderScene`, to stay independent of what ran before it.
175+
final ownDispatcher = EnginePlatformDispatcher();
176+
addTearDown(ownDispatcher.dispose);
177+
178+
final EngineFlutterView view = EnginePlatformDispatcher.instance.implicitView!;
179+
final displayFactory = DisplayCanvasFactory<DisplayCanvas>(
180+
createCanvas: () => FakeDisplayCanvas(),
181+
);
182+
final testRasterizer = TestRasterizer(view, displayFactory)
183+
..prepareCompleter = Completer<void>();
184+
final ViewRasterizer originalRasterizer = renderer.rasterizers[view.viewId]!;
185+
renderer.rasterizers[view.viewId] = testRasterizer;
186+
addTearDown(() => renderer.rasterizers[view.viewId] = originalRasterizer);
187+
188+
var firstFrameEventCount = 0;
189+
final firstFrameEvent = Completer<void>();
190+
final DomEventListener listener = createDomEventListener((DomEvent event) {
191+
firstFrameEventCount++;
192+
if (!firstFrameEvent.isCompleted) {
193+
firstFrameEvent.complete();
194+
}
195+
});
196+
domWindow.addEventListener('flutter-first-frame', listener);
197+
addTearDown(() => domWindow.removeEventListener('flutter-first-frame', listener));
198+
199+
// Wait for next frame.
200+
Future<void> waitForAnimationFrame() {
201+
final completer = Completer<void>();
202+
domWindow.requestAnimationFrame((_) {
203+
Timer.run(completer.complete);
204+
});
205+
return completer.future;
206+
}
207+
208+
final ui.Scene scene = ui.SceneBuilder().build();
209+
addTearDown(scene.dispose);
210+
late final Future<void> renderFuture;
211+
ownDispatcher.onDrawFrame = () {
212+
renderFuture = ownDispatcher.render(scene, view);
213+
};
214+
ownDispatcher.invokeOnDrawFrame();
215+
ownDispatcher.sendPlatformMessage(
216+
'flutter/service_worker',
217+
ByteData(0),
218+
(ByteData? response) {},
219+
);
220+
221+
// The render is parked in `prepareToDraw`, so the first frame is not
222+
// settled yet and the event is withheld.
223+
await waitForAnimationFrame();
224+
expect(firstFrameEventCount, 0);
225+
226+
// Failing the render settles the first frame too: `render` reports the
227+
// failure to its caller, and the event still goes out, so an app hiding its
228+
// loading screen on the event is not stuck on a failed frame.
229+
testRasterizer.prepareCompleter!.completeError(StateError('render failed'));
230+
await expectLater(renderFuture, throwsStateError);
231+
await expectLater(firstFrameEvent.future, completes);
232+
await waitForAnimationFrame();
233+
expect(firstFrameEventCount, 1);
234+
});
235+
92236
test('disposing platform view during prepareToDraw causes crash in submitFrame', () async {
93237
final EngineFlutterView view = EnginePlatformDispatcher.instance.implicitView!;
94238
final displayFactory = DisplayCanvasFactory<DisplayCanvas>(

0 commit comments

Comments
 (0)