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