Add more warm up frame docs #150464

loic-sharma · 2024-06-18T22:34:05Z

Updated the wiki to call out the warm up frame. This contains details from the following pages:

flutter/packages/flutter/lib/src/scheduler/binding.dart

Lines 994 to 1016 in b98d485

    
             /// ## Design discussion 
        
             /// 
        
             /// The Flutter engine prompts the framework to generate frames when it 
        
             /// receives a request from the operating system (known for historical reasons 
        
             /// as a vsync). However, this may not happen for several milliseconds after 
        
             /// the app starts (or after a hot reload). To make use of the time between 
        
             /// when the widget tree is first configured and when the engine requests an 
        
             /// update, the framework schedules a _warm-up frame_. 
        
             /// 
        
             /// A warm-up frame may never actually render (as the engine did not request 
        
             /// it and therefore does not have a valid context in which to paint), but it 
        
             /// will cause the framework to go through the steps of building, laying out, 
        
             /// and painting, which can together take several milliseconds. Thus, when the 
        
             /// engine requests a real frame, much of the work will already have been 
        
             /// completed, and the framework can generate the frame with minimal 
        
             /// additional effort. 
        
             /// 
        
             /// Warm-up frames are scheduled by [runApp] on startup, and by 
        
             /// [RendererBinding.performReassemble] during a hot reload. 
        
             /// 
        
             /// Warm-up frames are also scheduled when the framework is unblocked by a 
        
             /// call to [RendererBinding.allowFirstFrame] (corresponding to a call to 
        
             /// [RendererBinding.deferFirstFrame] that blocked the rendering).

https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/scheduleWarmUpFrame.html
https://api.flutter.dev/flutter/dart-ui/FlutterView/physicalSize.html

Part of #149974

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

goderbauer

LGTM

dkwingsmt · 2024-06-18T23:20:13Z

docs/engine/Life-of-a-Flutter-Frame.md

+A warm-up frame may never actually render (as the engine did not request
+it and therefore does not have a valid context in which to paint), but it


Suggested change

A warm-up frame may never actually render (as the engine did not request

it and therefore does not have a valid context in which to paint), but it

Depending on the platform implementation, the warm-up frame might cause the first frame to appear slightly earlier

than without, or might not be presented at all. In either case, it

I think the "engine context" is not important. And I suggest clarifying the side effect of the first frame time (if I understand the mechanism correctly)

Hm maybe instead of "engine context" I'll tweak this to say something like:

... as it invokes FlutterView.render outside of the scope of PlatformDispatcher.onBeginFrame or PlatformDispatcher.onDrawFrame

That phrasing would be more accurate while also giving some useful context. These are meant to be contributor-facing docs, so I think these kinds of details might be useful.

dkwingsmt · 2024-06-18T23:25:14Z

docs/engine/Life-of-a-Flutter-Frame.md

+and painting, which can together take several milliseconds. Thus, when the
+engine requests a real frame, much of the work will already have been
+completed, and the framework can generate the frame with minimal
+additional effort.


Suggested change

and painting, which can together take several milliseconds. Thus, when the

engine requests a real frame, much of the work will already have been

completed, and the framework can generate the frame with minimal

additional effort.

and painting, which allows the first real frame to be generated accumulatively, shortening the delay.

Maybe a more concise way?

I agree the current text is verbose, but I think it's clearer. Personally, I'd prefer to optimize for clarity here. (I stole this text from the framework's docs, not tooting my own horn here 😂)

dkwingsmt · 2024-06-18T23:25:53Z

docs/engine/Life-of-a-Flutter-Frame.md

+
+At startup, a warm-up frame can be produced before the Flutter engine has reported the
+initial view metrics using [PlatformDispatcher.onMetricsChanged][onMetricsChanged].
+As a result, the first frame can be produced with a size of zero.


Is this paragraph really needed? Is it something that really confuses people?

We can probably just count this case as another case of "the warm up frame is not presented at all".

Hey there, I agree this paragraph is a bit deep in the weeds. But this topic is the reason why I sent this pull request, as a follow-up to answering this question: #149974

I see, thanks for explanation!

dkwingsmt

Thanks for the work! In general I think this is good change. I have some suggestion, but none of them are strong.

If possible, it might be worthwhile asking someone who's not familiar with this topic to see if the docs make enough sense.

dkwingsmt · 2024-06-18T23:28:06Z

docs/engine/Life-of-a-Flutter-Frame.md

+
+At startup, a warm-up frame can be produced before the Flutter engine has reported the
+initial view metrics using [PlatformDispatcher.onMetricsChanged][onMetricsChanged].
+As a result, the first frame can be produced with a size of zero.


We can probably just count this case as another case of "the warm up frame is not presented at all".

* master: (23 commits) Roll pub packages (flutter#150810) Remove reference to `MaterialApp` and `showCupertinoModalPopup` from `CupertinoAlertDialog` (flutter#150725) Read `AndroidManifest.xml` and emit `manifest-impeller-(enabled|disabled)` analytics (flutter#150791) [flutter_tools] Shut down Chromium cleanly using a command sent through the debug protocol (flutter#150645) Reland fix inputDecorator hint color on M3 (flutter#150278) Roll Flutter Engine from 62e0b5f9c340 to 94023d711db3 (7 revisions) (flutter#150797) Fix collapsed InputDecorator minimum height (flutter#150770) Add more warm up frame docs (flutter#150464) Roll pub packages (flutter#150739) Add `focusNode`, `focusColor`, `onFocusChange`, `autofocus` to `CupertinoButton` (flutter#150721) Document RenderObject._relayoutBoundary and its invariant; small refactors (flutter#150527) Roll Flutter Engine from 6313b1e5afd7 to 62e0b5f9c340 (1 revision) (flutter#150790) fix a typo (flutter#150682) Fix link in RenderObjectWidget doc comment (flutter#150600) Roll Flutter Engine from fbd92055f3a6 to 6313b1e5afd7 (1 revision) (flutter#150781) [tool] make `ErrorHandlingFileSystem.deleteIfExists` catch error code 3 (`ERROR_PATH_NOT_FOUND` on Windows) (flutter#150741) Roll Packages from 711b4ac to 03f5f6d (21 revisions) (flutter#150779) Roll Flutter Engine from afa7ce19bca8 to fbd92055f3a6 (1 revision) (flutter#150777) Reland Add tests for form_text_field.1.dart (flutter#150481) (flutter#150696) (flutter#150750) Add an example for CupertinoPopupSurface (flutter#150357) ...

Manual roll Flutter from e726eb4 to 15f95ce (48 revisions) Manual roll requested by dit@google.com flutter/flutter@e726eb4...15f95ce 2024-06-28 engine-flutter-autoroll@skia.org Roll Flutter Engine from ddd4814b9d40 to 94591ffb20df (5 revisions) (flutter/flutter#150968) 2024-06-27 34871572+gmackall@users.noreply.github.com Manual engine roll to ddd4814 (flutter/flutter#150952) 2024-06-27 reidbaker@google.com local lint copy gradle task config (flutter/flutter#150957) 2024-06-27 engine-flutter-autoroll@skia.org Roll Flutter Engine from b42c80460538 to d1506c12808e (3 revisions) (flutter/flutter#150951) 2024-06-27 andrewrkolos@gmail.com [tool] make the `systemTempDirectory` getter on `ErrorHandlingFileSystem` wrap the underlying filesystem's temp directory in a`ErrorHandlingDirectory` (flutter/flutter#150876) 2024-06-27 jacksongardner@google.com Have flutter.js load local canvaskit instead of the CDN when appropriate (flutter/flutter#150806) 2024-06-27 engine-flutter-autoroll@skia.org Roll Flutter Engine from a9194f0f01f4 to b42c80460538 (10 revisions) (flutter/flutter#150940) 2024-06-27 jhy03261997@gmail.com [a11y] Reland [#149375 ] Update semantics in dropdown.dart (flutter/flutter#150578) 2024-06-27 goderbauer@google.com Bump dartdoc to 8.0.9+1 (flutter/flutter#150935) 2024-06-27 yjbanov@google.com add onFocus to text fields (flutter/flutter#150648) 2024-06-27 louisehsu@google.com Fixes `flutter build ipa` failure: Command line name "app-store" is deprecated. Use "app-store-connect" (flutter/flutter#150407) 2024-06-27 github@ricardoboss.de Copy any previous `IconThemeData` instead of overwriting it in CupertinoButton (flutter/flutter#149777) 2024-06-27 hans.muller@gmail.com Improve the behavior of scrollbar drag-scrolls triggered by the trackpad (flutter/flutter#150275) 2024-06-27 15272073+Fernthedev@users.noreply.github.com feat: Add autofocus for `MenuItemButton` (flutter/flutter#139396) 2024-06-27 engine-flutter-autoroll@skia.org Roll Flutter Engine from 1d5e3cc55a75 to a9194f0f01f4 (7 revisions) (flutter/flutter#150888) 2024-06-26 34871572+gmackall@users.noreply.github.com Reland "Remove dual_screen from new_gallery integration test" (flutter/flutter#150873) 2024-06-26 parlough@gmail.com Switch to more reliable flutter.dev link destinations in the tool (flutter/flutter#150587) 2024-06-26 goderbauer@google.com Adding `@docImport`s to the `animation` library (flutter/flutter#150798) 2024-06-26 magder@google.com Remove CODEOWNERS trailing whitespace (flutter/flutter#150882) 2024-06-26 engine-flutter-autoroll@skia.org Roll Flutter Engine from e03cf86c4170 to 1d5e3cc55a75 (3 revisions) (flutter/flutter#150875) 2024-06-26 matanlurey@users.noreply.github.com Remind folks we are moving. (flutter/flutter#150872) 2024-06-26 jacksongardner@google.com Remove `bringup: true` from web test shard. (flutter/flutter#150785) 2024-06-26 engine-flutter-autoroll@skia.org Roll Flutter Engine from c0017bed42c2 to e03cf86c4170 (1 revision) (flutter/flutter#150867) 2024-06-26 98614782+auto-submit[bot]@users.noreply.github.com Reverts "Remove `dual_screen` from `new_gallery` integration test (#150808)" (flutter/flutter#150871) 2024-06-26 34871572+gmackall@users.noreply.github.com Remove `dual_screen` from `new_gallery` integration test (flutter/flutter#150808) 2024-06-26 engine-flutter-autoroll@skia.org Roll Flutter Engine from d4624a36712b to c0017bed42c2 (4 revisions) (flutter/flutter#150865) 2024-06-26 swrenn@gmail.com Fixes for Style Guide for Flutter Repo (flutter/flutter#150167) 2024-06-26 engine-flutter-autoroll@skia.org Roll Flutter Engine from da62c629ed5c to d4624a36712b (3 revisions) (flutter/flutter#150852) 2024-06-26 sigurdm@google.com Use `Isolate.packageConfigSync! to locate the packageconfig of flutter tools (flutter/flutter#150340) 2024-06-26 engine-flutter-autoroll@skia.org Roll Flutter Engine from 25af762ffbb3 to da62c629ed5c (2 revisions) (flutter/flutter#150829) 2024-06-26 polinach@google.com Fix leaky tests. (flutter/flutter#150817) 2024-06-26 engine-flutter-autoroll@skia.org Roll Flutter Engine from 94023d711db3 to 25af762ffbb3 (4 revisions) (flutter/flutter#150818) 2024-06-26 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#150810) 2024-06-25 dkwingsmt@users.noreply.github.com Remove reference to `MaterialApp` and `showCupertinoModalPopup` from `CupertinoAlertDialog` (flutter/flutter#150725) 2024-06-25 matanlurey@users.noreply.github.com Read `AndroidManifest.xml` and emit `manifest-impeller-(enabled|disabled)` analytics (flutter/flutter#150791) 2024-06-25 jason-simmons@users.noreply.github.com [flutter_tools] Shut down Chromium cleanly using a command sent through the debug protocol (flutter/flutter#150645) 2024-06-25 bruno.leroux@gmail.com Reland fix inputDecorator hint color on M3 (flutter/flutter#150278) 2024-06-25 engine-flutter-autoroll@skia.org Roll Flutter Engine from 62e0b5f9c340 to 94023d711db3 (7 revisions) (flutter/flutter#150797) 2024-06-25 bruno.leroux@gmail.com Fix collapsed InputDecorator minimum height (flutter/flutter#150770) 2024-06-25 737941+loic-sharma@users.noreply.github.com Add more warm up frame docs (flutter/flutter#150464) 2024-06-25 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#150739) 2024-06-25 victorsanniay@gmail.com Add `focusNode`, `focusColor`, `onFocusChange`, `autofocus` to `CupertinoButton` (flutter/flutter#150721) 2024-06-25 greg@zulip.com Document RenderObject._relayoutBoundary and its invariant; small refactors (flutter/flutter#150527) 2024-06-25 engine-flutter-autoroll@skia.org Roll Flutter Engine from 6313b1e5afd7 to 62e0b5f9c340 (1 revision) (flutter/flutter#150790) ...

Add more warm up frame docs

fa41d50

loic-sharma requested review from goderbauer and dkwingsmt June 18, 2024 22:34

github-actions bot added engine flutter/engine repository. See also e: labels. team-engine Owned by Engine team d: docs/ flutter/flutter/docs, for contributors labels Jun 18, 2024

loic-sharma mentioned this pull request Jun 18, 2024

Layout on the iOS profile and release mode happens with zero max size first and then the actual max size. #149974

Closed

goderbauer approved these changes Jun 18, 2024

View reviewed changes

dkwingsmt reviewed Jun 18, 2024

View reviewed changes

dkwingsmt approved these changes Jun 18, 2024

View reviewed changes

loic-sharma and others added 2 commits June 24, 2024 14:16

Feedback

79cd380

Merge branch 'master' into first_frame_docs

2559743

loic-sharma added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 25, 2024

auto-submit bot merged commit 8334a31 into flutter:master Jun 25, 2024
29 checks passed

loic-sharma deleted the first_frame_docs branch June 25, 2024 21:03

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 26, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

08f14cf

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 26, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

8f27e05

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 26, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

c889535

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 27, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

58db652

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 27, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

a976034

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 27, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

e2c0393

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 28, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

50598fc

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 28, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

31597c9

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 28, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

6672d00

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 28, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

73f6037

engine-flutter-autoroll mentioned this pull request Jun 28, 2024

Roll Flutter from e726eb401c2c to 3a97a38c41f1 (53 revisions) flutter/packages#7008

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 28, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

8daf256

engine-flutter-autoroll mentioned this pull request Jun 28, 2024

Roll Flutter from e726eb401c2c to f5b671aac723 (54 revisions) flutter/packages#7009

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 28, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

99cfb71

loic-sharma mentioned this pull request Jul 11, 2024

Update Life-of-a-Flutter-Frame.md flutter/engine#53829

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 6, 2024

8334a31 Add more warm up frame docs (flutter/flutter#150464)

49a390b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add more warm up frame docs #150464

Add more warm up frame docs #150464

Uh oh!

loic-sharma commented Jun 18, 2024

Uh oh!

goderbauer left a comment

Uh oh!

dkwingsmt Jun 18, 2024 •

edited

Loading

Uh oh!

dkwingsmt Jun 18, 2024 •

edited

Loading

Uh oh!

loic-sharma Jun 24, 2024 •

edited

Loading

Uh oh!

dkwingsmt Jun 18, 2024

Uh oh!

loic-sharma Jun 24, 2024 •

edited

Loading

Uh oh!

dkwingsmt Jun 18, 2024

Uh oh!

dkwingsmt Jun 18, 2024

Uh oh!

loic-sharma Jun 24, 2024

Uh oh!

dkwingsmt Jun 24, 2024

Uh oh!

dkwingsmt left a comment

Uh oh!

dkwingsmt Jun 18, 2024

Uh oh!

Uh oh!

Uh oh!

	/// ## Design discussion
	///
	/// The Flutter engine prompts the framework to generate frames when it
	/// receives a request from the operating system (known for historical reasons
	/// as a vsync). However, this may not happen for several milliseconds after
	/// the app starts (or after a hot reload). To make use of the time between
	/// when the widget tree is first configured and when the engine requests an
	/// update, the framework schedules a _warm-up frame_.
	///
	/// A warm-up frame may never actually render (as the engine did not request
	/// it and therefore does not have a valid context in which to paint), but it
	/// will cause the framework to go through the steps of building, laying out,
	/// and painting, which can together take several milliseconds. Thus, when the
	/// engine requests a real frame, much of the work will already have been
	/// completed, and the framework can generate the frame with minimal
	/// additional effort.
	///
	/// Warm-up frames are scheduled by [runApp] on startup, and by
	/// [RendererBinding.performReassemble] during a hot reload.
	///
	/// Warm-up frames are also scheduled when the framework is unblocked by a
	/// call to [RendererBinding.allowFirstFrame] (corresponding to a call to
	/// [RendererBinding.deferFirstFrame] that blocked the rendering).

		A warm-up frame may never actually render (as the engine did not request
		it and therefore does not have a valid context in which to paint), but it

Add more warm up frame docs #150464

Add more warm up frame docs #150464

Uh oh!

Conversation

loic-sharma commented Jun 18, 2024

Pre-launch Checklist

Uh oh!

goderbauer left a comment

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

loic-sharma Jun 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

Uh oh!

loic-sharma Jun 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

Uh oh!

loic-sharma Jun 24, 2024

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 24, 2024

Choose a reason for hiding this comment

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dkwingsmt Jun 18, 2024 •

edited

Loading

dkwingsmt Jun 18, 2024 •

edited

Loading

loic-sharma Jun 24, 2024 •

edited

Loading

loic-sharma Jun 24, 2024 •

edited

Loading