Flutter Engine
pointer_data_dispatcher.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef POINTER_DATA_DISPATCHER_H_
6 #define POINTER_DATA_DISPATCHER_H_
7 
8 #include "flutter/runtime/runtime_controller.h"
9 #include "flutter/shell/common/animator.h"
10 
11 namespace flutter {
12 
13 class PointerDataDispatcher;
14 
15 //------------------------------------------------------------------------------
16 /// The `Engine` pointer data dispatcher that forwards the packet received from
17 /// `PlatformView::DispatchPointerDataPacket` on the platform thread, to
18 /// `Window::DispatchPointerDataPacket` on the UI thread.
19 ///
20 /// This class is used to filter the packets so the Flutter framework on the UI
21 /// thread will receive packets with some desired properties. See
22 /// `SmoothPointerDataDispatcher` for an example which filters irregularly
23 /// delivered packets, and dispatches them in sync with the VSYNC signal.
24 ///
25 /// This object will be owned by the engine because it relies on the engine's
26 /// `Animator` (which owns `VsyncWaiter`) and `RuntimeController` to do the
27 /// filtering. This object is currently designed to be only called from the UI
28 /// thread (no thread safety is guaranteed).
29 ///
30 /// The `PlatformView` decides which subclass of `PointerDataDispatcher` is
31 /// constructed by sending a `PointerDataDispatcherMaker` to the engine's
32 /// constructor in `Shell::CreateShellOnPlatformThread`. This is needed because:
33 /// (1) Different platforms (e.g., Android, iOS) have different dispatchers
34 /// so the decision has to be made per `PlatformView`.
35 /// (2) The `PlatformView` can only be accessed from the PlatformThread while
36 /// this class (as owned by engine) can only be accessed in the UI thread.
37 /// Hence `PlatformView` creates a `PointerDataDispatchMaker` on the
38 /// platform thread, and sends it to the UI thread for the final
39 /// construction of the `PointerDataDispatcher`.
41  public:
42  /// The interface for Engine to implement.
43  class Delegate {
44  public:
45  /// Actually dispatch the packet using Engine's `animator_` and
46  /// `runtime_controller_`.
47  virtual void DoDispatchPacket(std::unique_ptr<PointerDataPacket> packet,
48  uint64_t trace_flow_id) = 0;
49 
50  //--------------------------------------------------------------------------
51  /// @brief Schedule a secondary callback to be executed right after the
52  /// main `VsyncWaiter::AsyncWaitForVsync` callback (which is added
53  /// by `Animator::RequestFrame`).
54  ///
55  /// Like the callback in `AsyncWaitForVsync`, this callback is
56  /// only scheduled to be called once, and it will be called in the
57  /// UI thread. If there is no AsyncWaitForVsync callback
58  /// (`Animator::RequestFrame` is not called), this secondary
59  /// callback will still be executed at vsync.
60  ///
61  /// This callback is used to provide the vsync signal needed by
62  /// `SmoothPointerDataDispatcher`.
63  virtual void ScheduleSecondaryVsyncCallback(
64  const fml::closure& callback) = 0;
65  };
66 
67  //----------------------------------------------------------------------------
68  /// @brief Signal that `PlatformView` has a packet to be dispatched.
69  ///
70  /// @param[in] packet The `PointerDataPacket` to be dispatched.
71  /// @param[in] trace_flow_id The id for `Animator::EnqueueTraceFlowId`.
72  virtual void DispatchPacket(std::unique_ptr<PointerDataPacket> packet,
73  uint64_t trace_flow_id) = 0;
74 
75  //----------------------------------------------------------------------------
76  /// @brief Default destructor.
77  virtual ~PointerDataDispatcher();
78 };
79 
80 //------------------------------------------------------------------------------
81 /// The default dispatcher that forwards the packet without any modification.
82 ///
84  public:
86 
87  // |PointerDataDispatcer|
88  void DispatchPacket(std::unique_ptr<PointerDataPacket> packet,
89  uint64_t trace_flow_id) override;
90 
92 
93  protected:
95 
97 };
98 
99 //------------------------------------------------------------------------------
100 /// A dispatcher that may temporarily store and defer the last received
101 /// PointerDataPacket if multiple packets are received in one VSYNC. The
102 /// deferred packet will be sent in the next vsync in order to smooth out the
103 /// events. This filters out irregular input events delivery to provide a smooth
104 /// scroll on iPhone X/Xs.
105 ///
106 /// It works as follows:
107 ///
108 /// When `DispatchPacket` is called while a preivous pointer data dispatch is
109 /// still in progress (its frame isn't finished yet), it means that an input
110 /// event is delivered to us too fast. That potentially means a later event will
111 /// be too late which could cause the missing of a frame. Hence we'll cache it
112 /// in `pending_packet_` for the next frame to smooth it out.
113 ///
114 /// If the input event is sent to us regularly at the same rate of VSYNC (say
115 /// at 60Hz), this would be identical to `DefaultPointerDataDispatcher` where
116 /// `runtime_controller_->DispatchPointerDataPacket` is always called right
117 /// away. That's because `is_pointer_data_in_progress_` will always be false
118 /// when `DispatchPacket` is called since it will be cleared by the end of a
119 /// frame through `ScheduleSecondaryVsyncCallback`. This is the case for all
120 /// Android/iOS devices before iPhone X/XS.
121 ///
122 /// If the input event is irregular, but with a random latency of no more than
123 /// one frame, this would guarantee that we'll miss at most 1 frame. Without
124 /// this, we could miss half of the frames.
125 ///
126 /// If the input event is delivered at a higher rate than that of VSYNC, this
127 /// would at most add a latency of one event delivery. For example, if the
128 /// input event is delivered at 120Hz (this is only true for iPad pro, not even
129 /// iPhone X), this may delay the handling of an input event by 8ms.
130 ///
131 /// The assumption of this solution is that the sampling itself is still
132 /// regular. Only the event delivery is allowed to be irregular. So far this
133 /// assumption seems to hold on all devices. If it's changed in the future,
134 /// we'll need a different solution.
135 ///
136 /// See also input_events_unittests.cc where we test all our claims above.
138  public:
140 
141  // |PointerDataDispatcer|
142  void DispatchPacket(std::unique_ptr<PointerDataPacket> packet,
143  uint64_t trace_flow_id) override;
144 
145  virtual ~SmoothPointerDataDispatcher();
146 
147  private:
148  // If non-null, this will be a pending pointer data packet for the next frame
149  // to consume. This is used to smooth out the irregular drag events delivery.
150  // See also `DispatchPointerDataPacket` and input_events_unittests.cc.
151  std::unique_ptr<PointerDataPacket> pending_packet_;
152  int pending_trace_flow_id_ = -1;
153 
154  bool is_pointer_data_in_progress_ = false;
155 
157 
158  void DispatchPendingPacket();
159 
161 
163 };
164 
165 //--------------------------------------------------------------------------
166 /// @brief Signature for constructing PointerDataDispatcher.
167 ///
168 /// @param[in] delegate the `Flutter::Engine`
169 ///
171  std::function<std::unique_ptr<PointerDataDispatcher>(
173 
174 } // namespace flutter
175 
176 #endif // POINTER_DATA_DISPATCHER_H_
The interface for Engine to implement.
std::function< std::unique_ptr< PointerDataDispatcher >(PointerDataDispatcher::Delegate &)> PointerDataDispatcherMaker
Signature for constructing PointerDataDispatcher.
MockDelegate delegate_
std::function< void()> closure
Definition: closure.h:14
virtual ~PointerDataDispatcher()
Default destructor.
virtual void DispatchPacket(std::unique_ptr< PointerDataPacket > packet, uint64_t trace_flow_id)=0
Signal that PlatformView has a packet to be dispatched.
virtual void DoDispatchPacket(std::unique_ptr< PointerDataPacket > packet, uint64_t trace_flow_id)=0
virtual void ScheduleSecondaryVsyncCallback(const fml::closure &callback)=0
Schedule a secondary callback to be executed right after the main VsyncWaiter::AsyncWaitForVsync call...
#define FML_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: macros.h:27