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`. |
40 | class 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 | /// |
83 | class DefaultPointerDataDispatcher : public PointerDataDispatcher { |
84 | public: |
85 | DefaultPointerDataDispatcher(Delegate& delegate) : delegate_(delegate) {} |
86 | |
87 | // |PointerDataDispatcer| |
88 | void DispatchPacket(std::unique_ptr<PointerDataPacket> packet, |
89 | uint64_t trace_flow_id) override; |
90 | |
91 | virtual ~DefaultPointerDataDispatcher(); |
92 | |
93 | protected: |
94 | Delegate& delegate_; |
95 | |
96 | FML_DISALLOW_COPY_AND_ASSIGN(DefaultPointerDataDispatcher); |
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. |
137 | class SmoothPointerDataDispatcher : public DefaultPointerDataDispatcher { |
138 | public: |
139 | SmoothPointerDataDispatcher(Delegate& delegate); |
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 | |
156 | fml::WeakPtrFactory<SmoothPointerDataDispatcher> weak_factory_; |
157 | |
158 | void DispatchPendingPacket(); |
159 | |
160 | void ScheduleSecondaryVsyncCallback(); |
161 | |
162 | FML_DISALLOW_COPY_AND_ASSIGN(SmoothPointerDataDispatcher); |
163 | }; |
164 | |
165 | //-------------------------------------------------------------------------- |
166 | /// @brief Signature for constructing PointerDataDispatcher. |
167 | /// |
168 | /// @param[in] delegate the `Flutter::Engine` |
169 | /// |
170 | using PointerDataDispatcherMaker = |
171 | std::function<std::unique_ptr<PointerDataDispatcher>( |
172 | PointerDataDispatcher::Delegate&)>; |
173 | |
174 | } // namespace flutter |
175 | |
176 | #endif // POINTER_DATA_DISPATCHER_H_ |
177 | |