Add scheduleWarmUpFrame

lib/ui/dart_ui.cc

@@ -98,6 +98,7 @@ typedef CanvasPath Path;
   V(NativeStringAttribute::initSpellOutStringAttribute)            \
   V(PlatformConfigurationNativeApi::DefaultRouteName)              \
   V(PlatformConfigurationNativeApi::ScheduleFrame)                 \
+  V(PlatformConfigurationNativeApi::ForceSyncFrame)                \
   V(PlatformConfigurationNativeApi::Render)                        \
   V(PlatformConfigurationNativeApi::UpdateSemantics)               \
   V(PlatformConfigurationNativeApi::SetNeedsReportTimings)         \

lib/ui/platform_dispatcher.dart

@@ -801,11 +801,36 @@ class PlatformDispatcher {
   ///
   ///  * [SchedulerBinding], the Flutter framework class which manages the
   ///    scheduling of frames.
+  ///  * [forceSyncFrame], a similar method that is used in rare cases that
+  ///    a frame must be rendered immediately.
   void scheduleFrame() => _scheduleFrame();
 
   @Native<Void Function()>(symbol: 'PlatformConfigurationNativeApi::ScheduleFrame')
   external static void _scheduleFrame();
 
+  /// Immediately render a frame by invoking the [onBeginFrame] and
+  /// [onDrawFrame] callbacks synchronously.
+  ///
+  /// This method performs the same computation for a frame as [scheduleFrame]
+  /// does, but instead of doing so at an appropriate opportunity, the render is
+  /// completed synchronously within this call.
+  ///
+  /// Prefer [scheduleFrame] to update the display in normal operation. The
+  /// [forceSyncFrame] method is designed for situations that require a frame is
+  /// rendered as soon as possible, even at the cost of rendering quality. An
+  /// example of using this method is [SchedulerBinding.scheduleWarmUpFrame],
+  /// which is called during application startup so that the first frame can be
+  /// presented to the screen a few extra milliseconds earlier.
+  ///
+  /// See also:
+  ///
+  ///  * [SchedulerBinding.scheduleWarmUpFrame], which uses this method.
+  ///  * [scheduleFrame].
+  void forceSyncFrame() => _forceSyncFrame();
+
+  @Native<Void Function()>(symbol: 'PlatformConfigurationNativeApi::ForceSyncFrame')
+  external static void _forceSyncFrame();
+
   /// Additional accessibility features that may be enabled by the platform.
   AccessibilityFeatures get accessibilityFeatures => _configuration.accessibilityFeatures;
 

lib/ui/window/platform_configuration.cc

@@ -589,6 +589,11 @@ void PlatformConfigurationNativeApi::ScheduleFrame() {
   UIDartState::Current()->platform_configuration()->client()->ScheduleFrame();
 }
 
+void PlatformConfigurationNativeApi::ForceSyncFrame() {
+  UIDartState::ThrowIfUIOperationsProhibited();
+  UIDartState::Current()->platform_configuration()->client()->ForceSyncFrame();
+}
+
 void PlatformConfigurationNativeApi::UpdateSemantics(SemanticsUpdate* update) {
   UIDartState::ThrowIfUIOperationsProhibited();
   UIDartState::Current()->platform_configuration()->client()->UpdateSemantics(

lib/ui/window/platform_configuration.h

@@ -65,6 +65,11 @@ class PlatformConfigurationClient {
   ///
   virtual void ScheduleFrame() = 0;
 
+  //--------------------------------------------------------------------------
+  /// @brief
+  ///
+  virtual void ForceSyncFrame() = 0;
+
   //--------------------------------------------------------------------------
   /// @brief      Updates the client's rendering on the GPU with the newly
   ///             provided Scene.
@@ -557,6 +562,8 @@ class PlatformConfigurationNativeApi {
 
   static void ScheduleFrame();
 
+  static void ForceSyncFrame();
+
   static void Render(int64_t view_id,
                      Scene* scene,
                      double width,

lib/web_ui/lib/platform_dispatcher.dart

@@ -90,6 +90,8 @@ abstract class PlatformDispatcher {
 
   void scheduleFrame();
 
+  void forceSyncFrame();
+
   Future<void> render(Scene scene, [FlutterView view]);
 
   AccessibilityFeatures get accessibilityFeatures;

lib/web_ui/lib/src/engine/initialization.dart

@@ -102,6 +102,30 @@ void debugResetEngineInitializationState() {
   _initializationState = DebugEngineInitializationState.uninitialized;
 }
 
+void renderFrame(int timeInMicroseconds) {
+  frameTimingsOnVsync();
+
+  // In Flutter terminology "building a frame" consists of "beginning
+  // frame" and "drawing frame".
+  //
+  // We do not call `frameTimingsOnBuildFinish` from here because
+  // part of the rasterization process, particularly in the HTML
+  // renderer, takes place in the `SceneBuilder.build()`.
+  frameTimingsOnBuildStart();
+  if (EnginePlatformDispatcher.instance.onBeginFrame != null) {
+    EnginePlatformDispatcher.instance.invokeOnBeginFrame(
+        Duration(microseconds: timeInMicroseconds));
+  }
+
+  if (EnginePlatformDispatcher.instance.onDrawFrame != null) {
+    // TODO(yjbanov): technically Flutter flushes microtasks between
+    //                onBeginFrame and onDrawFrame. We don't, which hasn't
+    //                been an issue yet, but eventually we'll have to
+    //                implement it properly.
+    EnginePlatformDispatcher.instance.invokeOnDrawFrame();
+  }
+}
+
 /// Initializes non-UI engine services.
 ///
 /// Does not put any UI onto the page. It is therefore safe to call this
@@ -158,8 +182,6 @@ Future<void> initializeEngineServices({
     if (!waitingForAnimation) {
       waitingForAnimation = true;
       domWindow.requestAnimationFrame((JSNumber highResTime) {
-        frameTimingsOnVsync();
-
         // Reset immediately, because `frameHandler` can schedule more frames.
         waitingForAnimation = false;
 
@@ -170,29 +192,14 @@ Future<void> initializeEngineServices({
         // microsecond precision, and only then convert to `int`.
         final int highResTimeMicroseconds =
             (1000 * highResTime.toDartDouble).toInt();
-
-        // In Flutter terminology "building a frame" consists of "beginning
-        // frame" and "drawing frame".
-        //
-        // We do not call `frameTimingsOnBuildFinish` from here because
-        // part of the rasterization process, particularly in the HTML
-        // renderer, takes place in the `SceneBuilder.build()`.
-        frameTimingsOnBuildStart();
-        if (EnginePlatformDispatcher.instance.onBeginFrame != null) {
-          EnginePlatformDispatcher.instance.invokeOnBeginFrame(
-              Duration(microseconds: highResTimeMicroseconds));
-        }
-
-        if (EnginePlatformDispatcher.instance.onDrawFrame != null) {
-          // TODO(yjbanov): technically Flutter flushes microtasks between
-          //                onBeginFrame and onDrawFrame. We don't, which hasn't
-          //                been an issue yet, but eventually we'll have to
-          //                implement it properly.
-          EnginePlatformDispatcher.instance.invokeOnDrawFrame();
-        }
+        renderFrame(highResTimeMicroseconds);
       });
     }
   };
+  warmUpFrameCallback = () {
+    // TODO(dkwingsmt): Can we give it some time value?
+    renderFrame(0);
+  };
 
   assetManager ??= ui_web.AssetManager(assetBase: configuration.assetBase);
   _setAssetManager(assetManager);

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

@@ -17,6 +17,13 @@ import '../engine.dart';
 /// This may be overridden in tests, for example, to pump fake frames.
 ui.VoidCallback? scheduleFrameCallback;
 
+/// Requests that the framework tries to render a frame immediately.
+///
+/// Since this will probably call [PlatformWindow.render] outside of an
+/// animation frame, the render will not be actually presented, but just to warm
+/// up the framework.
+ui.VoidCallback? warmUpFrameCallback;
+
 /// Signature of functions added as a listener to high contrast changes
 typedef HighContrastListener = void Function(bool enabled);
 typedef _KeyDataResponseCallback = void Function(bool handled);
@@ -771,6 +778,14 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
     scheduleFrameCallback!();
   }
 
+  @override
+  void forceSyncFrame() {
+    if (warmUpFrameCallback == null) {
+      throw Exception('warmUpFrameCallback must be initialized first.');
+    }
+    warmUpFrameCallback!();
+  }
+
   /// Updates the application's rendering on the GPU with the newly provided
   /// [Scene]. This function must be called within the scope of the
   /// [onBeginFrame] or [onDrawFrame] callbacks being invoked. If this function

runtime/runtime_controller.cc

@@ -340,6 +340,11 @@ void RuntimeController::ScheduleFrame() {
   client_.ScheduleFrame();
 }
 
+// |PlatformConfigurationClient|
+void RuntimeController::ForceSyncFrame() {
+  client_.ForceSyncFrame();
+}
+
 // |PlatformConfigurationClient|
 void RuntimeController::Render(Scene* scene, double width, double height) {
   // TODO(dkwingsmt): Currently only supports a single window.

runtime/runtime_controller.h

@@ -657,6 +657,9 @@ class RuntimeController : public PlatformConfigurationClient {
   // |PlatformConfigurationClient|
   void ScheduleFrame() override;
 
+  // |PlatformConfigurationClient|
+  void ForceSyncFrame() override;
+
   // |PlatformConfigurationClient|
   void Render(Scene* scene, double width, double height) override;
 

runtime/runtime_delegate.h

@@ -25,6 +25,8 @@ class RuntimeDelegate {
 
   virtual void ScheduleFrame(bool regenerate_layer_trees = true) = 0;
 
+  virtual void ForceSyncFrame() = 0;
+
   virtual void Render(std::unique_ptr<flutter::LayerTree> layer_tree,
                       float device_pixel_ratio) = 0;
 

shell/common/animator.cc

@@ -264,6 +264,20 @@ void Animator::AwaitVSync() {
   }
 }
 
+void Animator::ForceSyncFrame() {
+  TRACE_EVENT_ASYNC_BEGIN0("flutter", "Forced Frame Request Pending",
+                           frame_request_number_);
+  regenerate_layer_trees_ = true;
+
+  const fml::TimePoint frame_start_time = fml::TimePoint::Now();
+  const fml::TimePoint frame_target_time = frame_start_time;
+
+  std::unique_ptr<FrameTimingsRecorder> frame_timings_recorder =
+      std::make_unique<FrameTimingsRecorder>();
+  frame_timings_recorder->RecordVsync(frame_start_time, frame_target_time);
+  BeginFrame(std::move(frame_timings_recorder));
+}
+
 void Animator::ScheduleSecondaryVsyncCallback(uintptr_t id,
                                               const fml::closure& callback) {
   waiter_->ScheduleSecondaryCallback(id, callback);

shell/common/animator.h

@@ -53,6 +53,8 @@ class Animator final {
 
   void RequestFrame(bool regenerate_layer_trees = true);
 
+  void ForceSyncFrame();
+
   //--------------------------------------------------------------------------
   /// @brief    Tells the Animator that this frame needs to render another view.
   ///

shell/common/engine.cc

@@ -462,6 +462,10 @@ void Engine::ScheduleFrame(bool regenerate_layer_trees) {
   animator_->RequestFrame(regenerate_layer_trees);
 }
 
+void Engine::ForceSyncFrame() {
+  animator_->ForceSyncFrame();
+}
+
 void Engine::Render(std::unique_ptr<flutter::LayerTree> layer_tree,
                     float device_pixel_ratio) {
   if (!layer_tree) {

shell/common/engine.h

@@ -837,6 +837,9 @@ class Engine final : public RuntimeDelegate, PointerDataDispatcher::Delegate {
   /// tree.
   void ScheduleFrame() { ScheduleFrame(true); }
 
+  // |RuntimeDelegate|
+  void ForceSyncFrame() override;
+
   // |RuntimeDelegate|
   FontCollection& GetFontCollection() override;
 

shell/common/engine_unittests.cc

@@ -63,6 +63,7 @@ class MockRuntimeDelegate : public RuntimeDelegate {
  public:
   MOCK_METHOD(std::string, DefaultRouteName, (), (override));
   MOCK_METHOD(void, ScheduleFrame, (bool), (override));
+  MOCK_METHOD(void, ForceSyncFrame, (), (override));
   MOCK_METHOD(void,
               Render,
               (std::unique_ptr<flutter::LayerTree>, float),