From 9dbd1e9872cce50ea4974c94920e59998761ebe6 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Tue, 8 Aug 2023 10:11:15 -0700 Subject: [PATCH] More documentation about warm-up frames (#132085) --- .../flutter/lib/src/scheduler/binding.dart | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/packages/flutter/lib/src/scheduler/binding.dart b/packages/flutter/lib/src/scheduler/binding.dart index 73b0971eb9622..2035b84927a11 100644 --- a/packages/flutter/lib/src/scheduler/binding.dart +++ b/packages/flutter/lib/src/scheduler/binding.dart @@ -933,6 +933,30 @@ mixin SchedulerBinding on BindingBase { /// [scheduleWarmUpFrame] was already called, this call will be ignored. /// /// Prefer [scheduleFrame] to update the display in normal operation. + /// + /// ## 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). void scheduleWarmUpFrame() { if (_warmUpFrame || schedulerPhase != SchedulerPhase.idle) { return;