Skip to content

Commit c4b0c5b

Browse files

File tree

1 file changed

+25
-1
lines changed

1 file changed

+25
-1
lines changed

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ Flutter does some minimal housekeeping when a frame is requested, primarily to i
1818

1919
Once a frame is scheduled, Flutter [waits for a vsync][vsyncWaiter] from the operating system to proceed.
2020

21-
2221
## Building the frame
2322

2423
At the heart of Flutter's graphics workflow is the frame [pipeline][pipeline]. The pipeline is responsible for coordinating work between the UI thread, where the application code runs, and the Raster thread, where rasterization and compositing is performed. See the [threading section][engineArchThreading] of the Engine Architecture wiki for more details on threading in the engine.
@@ -41,6 +40,28 @@ Once a surface is acquired, the [LayerTree][layerTree] is rasterized to the surf
4140

4241
The above process is repeated until the pipeline is empty.
4342

43+
## Warm-up frame
44+
45+
Normally, the Flutter framework begins producing a frame when it receives
46+
a vsync event from the operating system. However, this may not happen for
47+
several milliseconds after the app starts (or after a hot reload). To make
48+
use of the time between when the widget tree is first configured and when
49+
the engine requests an update, the framework schedules a _warm-up frame_
50+
using [PlatformDispatcher.scheduleWarmUpFrame][scheduleWarmUpFrame].
51+
52+
A warm-up frame may never actually render (as it invokes
53+
[FlutterView.render][flutterViewRender] outside of the scope of
54+
[PlatformDispatcher.onBeginFrame][onBeginFrame] or
55+
[PlatformDispatcher.onDrawFrame][onDrawFrame]), but it will cause the framework
56+
to go through the steps of building, laying out, and painting, which can
57+
together take several milliseconds. Thus, when the engine requests a real frame,
58+
much of the work will already have been completed, and the framework can
59+
generate the frame with minimal additional effort.
60+
61+
At startup, a warm-up frame can be produced before the Flutter engine has reported the
62+
initial view metrics using [PlatformDispatcher.onMetricsChanged][onMetricsChanged].
63+
As a result, the first frame can be produced with a size of zero.
64+
4465
## Cleaning up frame resources
4566

4667
TODO(cbracken): write this up using [this patch](https://github.com/flutter/engine/pull/38038) as a reminder.
@@ -53,10 +74,13 @@ TODO(cbracken): write this up using [this patch](https://github.com/flutter/engi
5374
[handleBeginFrame]: https://api.flutter.dev/flutter/scheduler/SchedulerBinding/handleBeginFrame.html
5475
[layerTree]: https://github.com/flutter/engine/blob/main/flow/layers/layer_tree.h
5576
[onBeginFrame]: https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onBeginFrame.html
77+
[onDrawFrame]: https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onDrawFrame.html
78+
[onMetricsChanged]: https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onMetricsChanged.html
5679
[pipeline]: https://github.com/flutter/engine/blob/main/shell/common/pipeline.h
5780
[rasterizer]: https://github.com/flutter/engine/blob/main/shell/common/rasterizer.h
5881
[renderingPipelineTalk]: https://www.youtube.com/watch?v=UUfXWzp0-DU
5982
[scene]: https://api.flutter.dev/flutter/dart-ui/Scene-class.html
83+
[scheduleWarmUpFrame]: https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/scheduleWarmUpFrame.html
6084
[surface]: https://github.com/flutter/engine/blob/main/flow/surface.h
6185
[scheduleFrame]: https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/scheduleFrame.html
6286
[vsyncWaiter]: https://github.com/flutter/engine/blob/main/shell/common/vsync_waiter.h

0 commit comments

Comments
 (0)