Flutter Windows Embedder
flutter_windows_engine.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 FLUTTER_SHELL_PLATFORM_WINDOWS_FLUTTER_WINDOWS_ENGINE_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_FLUTTER_WINDOWS_ENGINE_H_
7 
8 #include <chrono>
9 #include <map>
10 #include <memory>
11 #include <optional>
12 #include <shared_mutex>
13 #include <string>
14 #include <string_view>
15 #include <unordered_map>
16 #include <vector>
17 
18 #include "flutter/fml/closure.h"
19 #include "flutter/fml/macros.h"
25 #include "flutter/shell/platform/embedder/embedder.h"
48 #include "third_party/rapidjson/include/rapidjson/document.h"
49 
50 namespace flutter {
51 
52 // The implicit view's ID.
53 //
54 // See:
55 // https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/implicitView.html
57 
58 class FlutterWindowsView;
59 
60 // Update the thread priority for the Windows engine.
62  FlutterThreadPriority priority) {
63  // TODO(99502): Add support for tracing to the windows embedding so we can
64  // mark thread priorities and success/failure.
65  switch (priority) {
66  case FlutterThreadPriority::kBackground: {
67  SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_BELOW_NORMAL);
68  break;
69  }
70  case FlutterThreadPriority::kDisplay: {
71  SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_ABOVE_NORMAL);
72  break;
73  }
74  case FlutterThreadPriority::kRaster: {
75  SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_ABOVE_NORMAL);
76  break;
77  }
78  case FlutterThreadPriority::kNormal: {
79  // For normal or default priority we do not need to set the priority
80  // class.
81  break;
82  }
83  }
84 }
85 
86 // Manages state associated with the underlying FlutterEngine that isn't
87 // related to its display.
88 //
89 // In most cases this will be associated with a FlutterView, but if not will
90 // run in headless mode.
92  public:
93  // Creates a new Flutter engine object configured to run |project|.
95  const FlutterProjectBundle& project,
96  std::shared_ptr<WindowsProcTable> windows_proc_table = nullptr);
97 
98  virtual ~FlutterWindowsEngine();
99 
100  // Returns the engine associated with the given identifier.
101  // The engine_id must be valid and for a running engine, otherwise
102  // the behavior is undefined.
103  // Must be called on the platform thread.
104  static FlutterWindowsEngine* GetEngineForId(int64_t engine_id);
105 
106  // Starts running the entrypoint function specifed in the project bundle. If
107  // unspecified, defaults to main().
108  //
109  // Returns false if the engine couldn't be started.
110  bool Run();
111 
112  // Starts running the engine with the given entrypoint. If the empty string
113  // is specified, defaults to the entrypoint function specified in the project
114  // bundle, or main() if both are unspecified.
115  //
116  // Returns false if the engine couldn't be started or if conflicting,
117  // non-default values are passed here and in the project bundle..
118  //
119  // DEPRECATED: Prefer setting the entrypoint in the FlutterProjectBundle
120  // passed to the constructor and calling the no-parameter overload.
121  bool Run(std::string_view entrypoint);
122 
123  // Returns true if the engine is currently running.
124  virtual bool running() const { return engine_ != nullptr; }
125 
126  // Stops the engine. This invalidates the pointer returned by engine().
127  //
128  // Returns false if stopping the engine fails, or if it was not running.
129  virtual bool Stop();
130 
131  // Create a view that can display this engine's content.
132  //
133  // Returns null on failure.
134  std::unique_ptr<FlutterWindowsView> CreateView(
135  std::unique_ptr<WindowBindingHandler> window);
136 
137  // Remove a view. The engine will no longer render into it.
138  virtual void RemoveView(FlutterViewId view_id);
139 
140  // Get a view that displays this engine's content.
141  //
142  // Returns null if the view does not exist.
143  FlutterWindowsView* view(FlutterViewId view_id) const;
144 
145  // Returns the currently configured Plugin Registrar.
147 
148  // Registers |callback| to be called when the plugin registrar is destroyed.
152 
153  // Sets switches member to the given switches.
154  void SetSwitches(const std::vector<std::string>& switches);
155 
156  FlutterDesktopMessengerRef messenger() { return messenger_->ToRef(); }
157 
159  return message_dispatcher_.get();
160  }
161 
162  TaskRunner* task_runner() { return task_runner_.get(); }
163 
164  BinaryMessenger* messenger_wrapper() { return messenger_wrapper_.get(); }
165 
167  return texture_registrar_.get();
168  }
169 
170  // The EGL manager object. If this is nullptr, then we are
171  // rendering using software instead of OpenGL.
172  egl::Manager* egl_manager() const { return egl_manager_.get(); }
173 
175  return window_proc_delegate_manager_.get();
176  }
177 
178  // Informs the engine that the window metrics have changed.
179  void SendWindowMetricsEvent(const FlutterWindowMetricsEvent& event);
180 
181  // Informs the engine of an incoming pointer event.
182  void SendPointerEvent(const FlutterPointerEvent& event);
183 
184  // Informs the engine of an incoming key event.
185  void SendKeyEvent(const FlutterKeyEvent& event,
186  FlutterKeyEventCallback callback,
187  void* user_data);
188 
189  // Informs the engine of an incoming focus event.
190  void SendViewFocusEvent(const FlutterViewFocusEvent& event);
191 
193  return keyboard_key_handler_.get();
194  }
195  TextInputPlugin* text_input_plugin() { return text_input_plugin_.get(); }
196 
197  // Sends the given message to the engine, calling |reply| with |user_data|
198  // when a response is received from the engine if they are non-null.
199  bool SendPlatformMessage(const char* channel,
200  const uint8_t* message,
201  const size_t message_size,
202  const FlutterDesktopBinaryReply reply,
203  void* user_data);
204 
205  // Sends the given data as the response to an earlier platform message.
208  const uint8_t* data,
209  size_t data_length);
210 
211  // Callback passed to Flutter engine for notifying window of platform
212  // messages.
213  void HandlePlatformMessage(const FlutterPlatformMessage*);
214 
215  // Informs the engine that the system font list has changed.
216  void ReloadSystemFonts();
217 
218  // Informs the engine that a new frame is needed to redraw the content.
219  void ScheduleFrame();
220 
221  // Set the callback that is called when the next frame is drawn.
222  void SetNextFrameCallback(fml::closure callback);
223 
224  // Attempts to register the texture with the given |texture_id|.
225  bool RegisterExternalTexture(int64_t texture_id);
226 
227  // Attempts to unregister the texture with the given |texture_id|.
229 
230  // Notifies the engine about a new frame being available for the
231  // given |texture_id|.
233 
234  // Posts the given callback onto the raster thread.
235  virtual bool PostRasterThreadTask(fml::closure callback) const;
236 
237  // Invoke on the embedder's vsync callback to schedule a frame.
238  void OnVsync(intptr_t baton);
239 
240  // Dispatches a semantics action to the specified semantics node.
242  uint64_t node_id,
243  FlutterSemanticsAction action,
244  fml::MallocMapping data);
245 
246  // Informs the engine that the semantics enabled state has changed.
247  void UpdateSemanticsEnabled(bool enabled);
248 
249  // Returns true if the semantics tree is enabled.
250  bool semantics_enabled() const { return semantics_enabled_; }
251 
252  // Refresh accessibility features and send them to the engine.
254 
255  // Refresh high contrast accessibility mode and notify the engine.
256  void UpdateHighContrastMode();
257 
258  // Returns true if the high contrast feature is enabled.
259  bool high_contrast_enabled() const { return high_contrast_enabled_; }
260 
261  // Register a root isolate create callback.
262  //
263  // The root isolate create callback is invoked at creation of the root Dart
264  // isolate in the app. This may be used to be notified that execution of the
265  // main Dart entrypoint is about to begin, and is used by test infrastructure
266  // to register a native function resolver that can register and resolve
267  // functions marked as native in the Dart code.
268  //
269  // This must be called before calling |Run|.
270  void SetRootIsolateCreateCallback(const fml::closure& callback) {
271  root_isolate_create_callback_ = callback;
272  }
273 
274  // Returns the executable name for this process or "Flutter" if unknown.
275  std::string GetExecutableName() const;
276 
277  // Called when the application quits in response to a quit request.
278  void OnQuit(std::optional<HWND> hwnd,
279  std::optional<WPARAM> wparam,
280  std::optional<LPARAM> lparam,
281  UINT exit_code);
282 
283  // Called when a WM_CLOSE message is received.
284  void RequestApplicationQuit(HWND hwnd,
285  WPARAM wparam,
286  LPARAM lparam,
287  AppExitType exit_type);
288 
289  // Called when a WM_DWMCOMPOSITIONCHANGED message is received.
291 
292  // Called when a Window receives an event that may alter the application
293  // lifecycle state.
294  void OnWindowStateEvent(HWND hwnd, WindowStateEvent event);
295 
296  // Handle a message from a non-Flutter window in the same application.
297  // Returns a result when the message is consumed and should not be processed
298  // further.
299  std::optional<LRESULT> ProcessExternalWindowMessage(HWND hwnd,
300  UINT message,
301  WPARAM wparam,
302  LPARAM lparam);
303 
305  return lifecycle_manager_.get();
306  }
307 
308  std::shared_ptr<WindowsProcTable> windows_proc_table() {
309  return windows_proc_table_;
310  }
311 
312  // Sets the cursor that should be used when the mouse is over the Flutter
313  // content. See mouse_cursor.dart for the values and meanings of cursor_name.
314  void UpdateFlutterCursor(const std::string& cursor_name) const;
315 
316  // Sets the cursor directly from a cursor handle.
317  void SetFlutterCursor(HCURSOR cursor) const;
318 
319  WindowManager* window_manager() { return window_manager_.get(); }
320 
321  // Returns the root view associated with the top-level window with |hwnd| as
322  // the window handle or nullptr if no such view could be found.
324 
325  protected:
326  // Creates the keyboard key handler.
327  //
328  // Exposing this method allows unit tests to override in order to
329  // capture information.
330  virtual std::unique_ptr<KeyboardHandlerBase> CreateKeyboardKeyHandler(
334 
335  // Creates the text input plugin.
336  //
337  // Exposing this method allows unit tests to override in order to
338  // capture information.
339  virtual std::unique_ptr<TextInputPlugin> CreateTextInputPlugin(
341 
342  // Invoked by the engine right before the engine is restarted.
343  //
344  // This should reset necessary states to as if the engine has just been
345  // created. This is typically caused by a hot restart (Shift-R in CLI.)
346  void OnPreEngineRestart();
347 
348  // Invoked by the engine when a listener is set or cleared on a platform
349  // channel.
350  virtual void OnChannelUpdate(std::string name, bool listening);
351 
352  virtual void OnViewFocusChangeRequest(
353  const FlutterViewFocusChangeRequest* request);
354 
355  private:
356  // Allows swapping out embedder_api_ calls in tests.
357  friend class EngineModifier;
358 
359  // Maps a Flutter cursor name to an HCURSOR.
360  //
361  // Returns the arrow cursor for unknown constants.
362  //
363  // This map must be kept in sync with Flutter framework's
364  // services/mouse_cursor.dart.
365  HCURSOR GetCursorByName(const std::string& cursor_name) const;
366 
367  // Sends system locales to the engine.
368  //
369  // Should be called just after the engine is run, and after any relevant
370  // system changes.
371  void SendSystemLocales();
372 
373  // Create the keyboard & text input sub-systems.
374  //
375  // This requires that a view is attached to the engine.
376  // Calling this method again resets the keyboard state.
377  void InitializeKeyboard();
378 
379  // Send the currently enabled accessibility features to the engine.
380  void SendAccessibilityFeatures();
381 
382  // Present content to a view. Returns true if the content was presented.
383  //
384  // This is invoked on the raster thread.
385  bool Present(const FlutterPresentViewInfo* info);
386 
387  // The handle to the embedder.h engine instance.
388  FLUTTER_API_SYMBOL(FlutterEngine) engine_ = nullptr;
389 
390  FlutterEngineProcTable embedder_api_ = {};
391 
392  std::unique_ptr<FlutterProjectBundle> project_;
393 
394  // AOT data, if any.
395  UniqueAotDataPtr aot_data_;
396 
397  // The ID that the next view will have.
398  FlutterViewId next_view_id_ = kImplicitViewId;
399 
400  // The views displaying the content running in this engine, if any.
401  //
402  // This is read and mutated by the platform thread. This is read by the raster
403  // thread to present content to a view.
404  //
405  // Reads to this object on non-platform threads must be protected
406  // by acquiring a shared lock on |views_mutex_|.
407  //
408  // Writes to this object must only happen on the platform thread
409  // and must be protected by acquiring an exclusive lock on |views_mutex_|.
410  std::unordered_map<FlutterViewId, FlutterWindowsView*> views_;
411 
412  // The mutex that protects the |views_| map.
413  //
414  // The raster thread acquires a shared lock to present to a view.
415  //
416  // The platform thread acquires a shared lock to access the view.
417  // The platform thread acquires an exclusive lock before adding
418  // a view to the engine or after removing a view from the engine.
419  mutable std::shared_mutex views_mutex_;
420 
421  // Task runner for tasks posted from the engine.
422  std::unique_ptr<TaskRunner> task_runner_;
423 
424  // The plugin messenger handle given to API clients.
425  fml::RefPtr<flutter::FlutterDesktopMessenger> messenger_;
426 
427  // A wrapper around messenger_ for interacting with client_wrapper-level APIs.
428  std::unique_ptr<BinaryMessengerImpl> messenger_wrapper_;
429 
430  // Message dispatch manager for messages from engine_.
431  std::unique_ptr<IncomingMessageDispatcher> message_dispatcher_;
432 
433  // The plugin registrar handle given to API clients.
434  std::unique_ptr<FlutterDesktopPluginRegistrar> plugin_registrar_;
435 
436  // The texture registrar.
437  std::unique_ptr<FlutterWindowsTextureRegistrar> texture_registrar_;
438 
439  // An object used for intializing ANGLE and creating / destroying render
440  // surfaces. If nullptr, ANGLE failed to initialize and software rendering
441  // should be used instead.
442  std::unique_ptr<egl::Manager> egl_manager_;
443 
444  // The compositor that creates backing stores for the engine to render into
445  // and then presents them onto views.
446  std::unique_ptr<Compositor> compositor_;
447 
448  // The plugin registrar managing internal plugins.
449  std::unique_ptr<PluginRegistrar> internal_plugin_registrar_;
450 
451  // Handler for accessibility events.
452  std::unique_ptr<AccessibilityPlugin> accessibility_plugin_;
453 
454  // Handler for cursor events.
455  std::unique_ptr<CursorHandler> cursor_handler_;
456 
457  // Handler for the flutter/platform channel.
458  std::unique_ptr<PlatformHandler> platform_handler_;
459 
460  // Handlers for keyboard events from Windows.
461  std::unique_ptr<KeyboardHandlerBase> keyboard_key_handler_;
462 
463  // The manager that manages the lifecycle of |HostWindow|s, native
464  // Win32 windows hosting a Flutter view in their client area.
465  std::unique_ptr<WindowManager> window_manager_;
466 
467  // Handlers for text events from Windows.
468  std::unique_ptr<TextInputPlugin> text_input_plugin_;
469 
470  // The settings plugin.
471  std::unique_ptr<SettingsPlugin> settings_plugin_;
472 
473  // Callbacks to be called when the engine (and thus the plugin registrar) is
474  // being destroyed.
477  plugin_registrar_destruction_callbacks_;
478 
479  // The approximate time between vblank events.
480  std::chrono::nanoseconds FrameInterval();
481 
482  // The start time used to align frames.
483  std::chrono::nanoseconds start_time_ = std::chrono::nanoseconds::zero();
484 
485  // An override of the frame interval used by EngineModifier for testing.
486  std::optional<std::chrono::nanoseconds> frame_interval_override_ =
487  std::nullopt;
488 
489  bool semantics_enabled_ = false;
490 
491  bool high_contrast_enabled_ = false;
492 
493  bool enable_impeller_ = false;
494 
495  // The manager for WindowProc delegate registration and callbacks.
496  std::unique_ptr<WindowProcDelegateManager> window_proc_delegate_manager_;
497 
498  // The root isolate creation callback.
499  fml::closure root_isolate_create_callback_;
500 
501  // The on frame drawn callback.
502  fml::closure next_frame_callback_;
503 
504  // Handler for top level window messages.
505  std::unique_ptr<WindowsLifecycleManager> lifecycle_manager_;
506 
507  std::shared_ptr<WindowsProcTable> windows_proc_table_;
508 
509  std::shared_ptr<egl::ProcTable> gl_;
510 
511  std::unique_ptr<PlatformViewPlugin> platform_view_plugin_;
512 
513  FML_DISALLOW_COPY_AND_ASSIGN(FlutterWindowsEngine);
514 };
515 
516 } // namespace flutter
517 
518 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_FLUTTER_WINDOWS_ENGINE_H_
FlutterWindowsTextureRegistrar * texture_registrar()
std::shared_ptr< WindowsProcTable > windows_proc_table()
FlutterWindowsEngine(const FlutterProjectBundle &project, std::shared_ptr< WindowsProcTable > windows_proc_table=nullptr)
FlutterDesktopMessengerRef messenger()
WindowsLifecycleManager * lifecycle_manager()
void OnWindowStateEvent(HWND hwnd, WindowStateEvent event)
void RequestApplicationQuit(HWND hwnd, WPARAM wparam, LPARAM lparam, AppExitType exit_type)
WindowProcDelegateManager * window_proc_delegate_manager()
FlutterWindowsView * view(FlutterViewId view_id) const
void SendViewFocusEvent(const FlutterViewFocusEvent &event)
bool SendPlatformMessage(const char *channel, const uint8_t *message, const size_t message_size, const FlutterDesktopBinaryReply reply, void *user_data)
virtual void OnViewFocusChangeRequest(const FlutterViewFocusChangeRequest *request)
std::optional< LRESULT > ProcessExternalWindowMessage(HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
void AddPluginRegistrarDestructionCallback(FlutterDesktopOnPluginRegistrarDestroyed callback, FlutterDesktopPluginRegistrarRef registrar)
bool RegisterExternalTexture(int64_t texture_id)
void SendPlatformMessageResponse(const FlutterDesktopMessageResponseHandle *handle, const uint8_t *data, size_t data_length)
void SetRootIsolateCreateCallback(const fml::closure &callback)
static FlutterWindowsEngine * GetEngineForId(int64_t engine_id)
virtual void OnChannelUpdate(std::string name, bool listening)
virtual std::unique_ptr< KeyboardHandlerBase > CreateKeyboardKeyHandler(BinaryMessenger *messenger, KeyboardKeyEmbedderHandler::GetKeyStateHandler get_key_state, KeyboardKeyEmbedderHandler::MapVirtualKeyToScanCode map_vk_to_scan)
bool DispatchSemanticsAction(FlutterViewId view_id, uint64_t node_id, FlutterSemanticsAction action, fml::MallocMapping data)
bool MarkExternalTextureFrameAvailable(int64_t texture_id)
FlutterWindowsView * GetViewFromTopLevelWindow(HWND hwnd) const
KeyboardHandlerBase * keyboard_key_handler()
std::unique_ptr< FlutterWindowsView > CreateView(std::unique_ptr< WindowBindingHandler > window)
virtual bool PostRasterThreadTask(fml::closure callback) const
IncomingMessageDispatcher * message_dispatcher()
bool UnregisterExternalTexture(int64_t texture_id)
void SetNextFrameCallback(fml::closure callback)
void HandlePlatformMessage(const FlutterPlatformMessage *)
virtual void RemoveView(FlutterViewId view_id)
FlutterDesktopPluginRegistrarRef GetRegistrar()
virtual std::unique_ptr< TextInputPlugin > CreateTextInputPlugin(BinaryMessenger *messenger)
void UpdateFlutterCursor(const std::string &cursor_name) const
void SetFlutterCursor(HCURSOR cursor) const
void SendPointerEvent(const FlutterPointerEvent &event)
void SendWindowMetricsEvent(const FlutterWindowMetricsEvent &event)
void SetSwitches(const std::vector< std::string > &switches)
void SendKeyEvent(const FlutterKeyEvent &event, FlutterKeyEventCallback callback, void *user_data)
void OnQuit(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, UINT exit_code)
std::function< SHORT(UINT, bool)> MapVirtualKeyToScanCode
uint32_t texture_id
void(* FlutterDesktopBinaryReply)(const uint8_t *data, size_t data_size, void *user_data)
struct FlutterDesktopMessenger * FlutterDesktopMessengerRef
struct _FlutterPlatformMessageResponseHandle FlutterDesktopMessageResponseHandle
void(* FlutterDesktopOnPluginRegistrarDestroyed)(FlutterDesktopPluginRegistrarRef)
FlutterDesktopBinaryReply callback
Win32Message message
WindowStateEvent
An event representing a change in window state that may update the.
int64_t FlutterViewId
Definition: flutter_view.h:13
static void WindowsPlatformThreadPrioritySetter(FlutterThreadPriority priority)
constexpr FlutterViewId kImplicitViewId
std::unique_ptr< _FlutterEngineAOTData, FlutterEngineCollectAOTDataFnPtr > UniqueAotDataPtr