Embedder API Support for display settings (flutter#21355)

Embedders can now notify shell during startup about the various displays and their corresponding settings.
Adds a notion of Display update type which can later include chages to displays during runtime such as addition / removal / reconfiguration of displays.

We also remove the responsibility of providing the refresh rate from `vsync_waiter` to `DisplayManager`.
Rewires existing platform implementations of the said API to use `Shell::OnDisplayUpdate` to notify the display manager of the startup configuration.

DisplayManager is also thread-safe to account for rasterizer and UI thread accesses.

Author: iskakaushik

ci/licenses_golden/licenses_flutter

@@ -599,6 +599,9 @@ FILE: ../../../flutter/shell/common/animator_unittests.cc
 FILE: ../../../flutter/shell/common/canvas_spy.cc
 FILE: ../../../flutter/shell/common/canvas_spy.h
 FILE: ../../../flutter/shell/common/canvas_spy_unittests.cc
+FILE: ../../../flutter/shell/common/display.h
+FILE: ../../../flutter/shell/common/display_manager.cc
+FILE: ../../../flutter/shell/common/display_manager.h
 FILE: ../../../flutter/shell/common/engine.cc
 FILE: ../../../flutter/shell/common/engine.h
 FILE: ../../../flutter/shell/common/engine_unittests.cc

shell/common/BUILD.gn

@@ -64,6 +64,9 @@ source_set("common") {
     "animator.h",
     "canvas_spy.cc",
     "canvas_spy.h",
+    "display.h",
+    "display_manager.cc",
+    "display_manager.h",
     "engine.cc",
     "engine.h",
     "isolate_configuration.cc",

shell/common/animator.cc

@@ -53,10 +53,6 @@ Animator::Animator(Delegate& delegate,
 
 Animator::~Animator() = default;
 
-float Animator::GetDisplayRefreshRate() const {
-  return waiter_->GetDisplayRefreshRate();
-}
-
 void Animator::Stop() {
   paused_ = true;
 }

shell/common/animator.h

@@ -47,8 +47,6 @@ class Animator final {
 
   ~Animator();
 
-  float GetDisplayRefreshRate() const;
-
   void RequestFrame(bool regenerate_layer_tree = true);
 
   void Render(std::unique_ptr<flutter::LayerTree> layer_tree);

shell/common/display.h

@@ -0,0 +1,55 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_SHELL_COMMON_DISPLAY_H_
+#define FLUTTER_SHELL_COMMON_DISPLAY_H_
+
+#include <optional>
+
+namespace flutter {
+
+/// Unique ID per display that is stable until the Flutter application restarts.
+/// See also: `flutter::Display`
+typedef uint64_t DisplayId;
+
+/// To be used when the display refresh rate is unknown.
+static constexpr double kUnknownDisplayRefreshRate = 0;
+
+/// Display refers to a graphics hardware system consisting of a framebuffer,
+/// typically a monitor or a screen. This class holds the various display
+/// settings.
+class Display {
+ public:
+  //------------------------------------------------------------------------------
+  /// @brief Construct a new Display object in case where the display id of the
+  /// display is known. In cases where there is more than one display, every
+  /// display is expected to have a display id.
+  ///
+  Display(DisplayId display_id, double refresh_rate)
+      : display_id_(display_id), refresh_rate_(refresh_rate) {}
+
+  //------------------------------------------------------------------------------
+  /// @brief Construct a new Display object when there is only a single display.
+  /// When there are multiple displays, every display must have a display id.
+  ///
+  explicit Display(double refresh_rate)
+      : display_id_({}), refresh_rate_(refresh_rate) {}
+
+  ~Display() = default;
+
+  // Get the display's maximum refresh rate in the unit of frame per second.
+  // Return `kUnknownDisplayRefreshRate` if the refresh rate is unknown.
+  double GetRefreshRate() const { return refresh_rate_; }
+
+  /// Returns the `DisplayId` of the display.
+  std::optional<DisplayId> GetDisplayId() const { return display_id_; }
+
+ private:
+  std::optional<DisplayId> display_id_;
+  double refresh_rate_;
+};
+
+}  // namespace flutter
+
+#endif  // FLUTTER_SHELL_COMMON_DISPLAY_H_

shell/common/display_manager.cc

@@ -0,0 +1,49 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "flutter/shell/common/display_manager.h"
+
+#include "flutter/fml/logging.h"
+#include "flutter/fml/macros.h"
+
+namespace flutter {
+
+DisplayManager::DisplayManager() = default;
+
+DisplayManager::~DisplayManager() = default;
+
+double DisplayManager::GetMainDisplayRefreshRate() const {
+  std::scoped_lock lock(displays_mutex_);
+  if (displays_.empty()) {
+    return kUnknownDisplayRefreshRate;
+  } else {
+    return displays_[0].GetRefreshRate();
+  }
+}
+
+void DisplayManager::HandleDisplayUpdates(DisplayUpdateType update_type,
+                                          std::vector<Display> displays) {
+  std::scoped_lock lock(displays_mutex_);
+  CheckDisplayConfiguration(displays);
+  switch (update_type) {
+    case DisplayUpdateType::kStartup:
+      FML_CHECK(displays_.empty());
+      displays_ = displays;
+      return;
+    default:
+      FML_CHECK(false) << "Unknown DisplayUpdateType.";
+  }
+}
+
+void DisplayManager::CheckDisplayConfiguration(
+    std::vector<Display> displays) const {
+  FML_CHECK(!displays.empty());
+  if (displays.size() > 1) {
+    for (auto& display : displays) {
+      FML_CHECK(display.GetDisplayId().has_value());
+    }
+  }
+}
+
+}  // namespace flutter

shell/common/display_manager.h

@@ -0,0 +1,59 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_SHELL_COMMON_DISPLAY_MANAGER_H_
+#define FLUTTER_SHELL_COMMON_DISPLAY_MANAGER_H_
+
+#include <mutex>
+#include <vector>
+
+#include "flutter/shell/common/display.h"
+
+namespace flutter {
+
+/// The update type parameter that is passed to
+/// `DisplayManager::HandleDisplayUpdates`.
+enum class DisplayUpdateType {
+  /// `flutter::Display`s that were active during start-up. A display is
+  /// considered active if:
+  ///    1. The frame buffer hardware is connected.
+  ///    2. The display is drawable, e.g. it isn't being mirrored from another
+  ///       connected display or sleeping.
+  kStartup
+};
+
+/// Manages lifecycle of the connected displays. This class is thread-safe.
+class DisplayManager {
+ public:
+  DisplayManager();
+
+  ~DisplayManager();
+
+  /// Returns the display refresh rate of the main display. In cases where there
+  /// is only one display connected, it will return that. We do not yet support
+  /// cases where there are multiple displays.
+  ///
+  /// When there are no registered displays, it returns
+  /// `kUnknownDisplayRefreshRate`.
+  double GetMainDisplayRefreshRate() const;
+
+  /// Handles the display updates.
+  void HandleDisplayUpdates(DisplayUpdateType update_type,
+                            std::vector<Display> displays);
+
+ private:
+  /// Guards `displays_` vector.
+  mutable std::mutex displays_mutex_;
+  std::vector<Display> displays_;
+
+  /// Checks that the provided display configuration is valid. Currently this
+  /// ensures that all the displays have an id in the case there are multiple
+  /// displays. In case where there is a single display, it is valid for the
+  /// display to not have an id.
+  void CheckDisplayConfiguration(std::vector<Display> displays) const;
+};
+
+}  // namespace flutter
+
+#endif  // FLUTTER_SHELL_COMMON_DISPLAY_MANAGER_H_

shell/common/engine.cc

@@ -97,10 +97,6 @@ Engine::Engine(Delegate& delegate,
 
 Engine::~Engine() = default;
 
-float Engine::GetDisplayRefreshRate() const {
-  return animator_->GetDisplayRefreshRate();
-}
-
 fml::WeakPtr<Engine> Engine::GetWeakPtr() const {
   return weak_factory_.GetWeakPtr();
 }

shell/common/engine.h

@@ -24,6 +24,7 @@
 #include "flutter/runtime/runtime_controller.h"
 #include "flutter/runtime/runtime_delegate.h"
 #include "flutter/shell/common/animator.h"
+#include "flutter/shell/common/display_manager.h"
 #include "flutter/shell/common/platform_view.h"
 #include "flutter/shell/common/pointer_data_dispatcher.h"
 #include "flutter/shell/common/rasterizer.h"
@@ -328,30 +329,6 @@ class Engine final : public RuntimeDelegate,
   ///
   ~Engine() override;
 
-  //----------------------------------------------------------------------------
-  /// @brief      Gets the refresh rate in frames per second of the vsync waiter
-  ///             used by the animator managed by this engine. This information
-  ///             is purely advisory and is not used by any component. It is
-  ///             only used by the tooling to visualize frame performance.
-  ///
-  /// @attention  The display refresh rate is useless for frame scheduling
-  ///             because it can vary and more accurate frame specific
-  ///             information is given to the engine by the vsync waiter
-  ///             already. However, this call is used by the tooling to ask very
-  ///             high level questions about display refresh rate. For example,
-  ///             "Is the display 60 or 120Hz?". This information is quite
-  ///             unreliable (not available immediately on launch on some
-  ///             platforms), variable and advisory. It must not be used by any
-  ///             component that claims to use it to perform accurate frame
-  ///             scheduling.
-  ///
-  /// @return     The display refresh rate in frames per second. This may change
-  ///             from frame to frame, throughout the lifecycle of the
-  ///             application, and, may not be available immediately upon
-  ///             application launch.
-  ///
-  float GetDisplayRefreshRate() const;
-
   //----------------------------------------------------------------------------
   /// @return     The pointer to this instance of the engine. The engine may
   ///             only be accessed safely on the UI task runner.

shell/common/rasterizer.h

@@ -68,7 +68,9 @@ class Rasterizer final : public SnapshotDelegate {
     ///
     virtual void OnFrameRasterized(const FrameTiming& frame_timing) = 0;
 
-    /// Time limit for a smooth frame. See `Engine::GetDisplayRefreshRate`.
+    /// Time limit for a smooth frame.
+    ///
+    /// See: `DisplayManager::GetMainDisplayRefreshRate`.
     virtual fml::Milliseconds GetFrameBudget() = 0;
 
     /// Target time for the latest frame. See also `Shell::OnAnimatorBeginFrame`