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 711b4ac2794e to 03f5f6d5660c (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) ...

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

8334a3172 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

8334a3172 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

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

c889535

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add more warm up frame docs #150464

Add more warm up frame docs #150464

loic-sharma commented Jun 18, 2024

goderbauer left a comment

dkwingsmt Jun 18, 2024 •

edited

Loading

dkwingsmt Jun 18, 2024 •

edited

Loading

loic-sharma Jun 24, 2024 •

edited

Loading

dkwingsmt Jun 18, 2024

loic-sharma Jun 24, 2024 •

edited

Loading

dkwingsmt Jun 18, 2024

dkwingsmt Jun 18, 2024

loic-sharma Jun 24, 2024

dkwingsmt Jun 24, 2024

dkwingsmt left a comment

dkwingsmt Jun 18, 2024

	/// ## 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

Conversation

loic-sharma commented Jun 18, 2024

Pre-launch Checklist

goderbauer left a comment

Choose a reason for hiding this comment

dkwingsmt Jun 18, 2024 • edited Loading

Choose a reason for hiding this comment

dkwingsmt Jun 18, 2024 • edited Loading

Choose a reason for hiding this comment

loic-sharma Jun 24, 2024 • edited Loading

Choose a reason for hiding this comment

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

loic-sharma Jun 24, 2024 • edited Loading

Choose a reason for hiding this comment

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

loic-sharma Jun 24, 2024

Choose a reason for hiding this comment

dkwingsmt Jun 24, 2024

Choose a reason for hiding this comment

dkwingsmt left a comment

Choose a reason for hiding this comment

dkwingsmt Jun 18, 2024

Choose a reason for hiding this comment

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