Flutter Engine
platform_view.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 COMMON_PLATFORM_VIEW_H_
6 #define COMMON_PLATFORM_VIEW_H_
7 
8 #include <functional>
9 #include <memory>
10 
11 #include "flutter/common/graphics/texture.h"
12 #include "flutter/common/task_runners.h"
13 #include "flutter/flow/embedded_views.h"
14 #include "flutter/flow/surface.h"
15 #include "flutter/fml/macros.h"
16 #include "flutter/fml/mapping.h"
17 #include "flutter/fml/memory/weak_ptr.h"
18 #include "flutter/lib/ui/semantics/custom_accessibility_action.h"
19 #include "flutter/lib/ui/semantics/semantics_node.h"
20 #include "flutter/lib/ui/window/key_data_packet.h"
21 #include "flutter/lib/ui/window/platform_message.h"
22 #include "flutter/lib/ui/window/pointer_data_packet.h"
23 #include "flutter/lib/ui/window/pointer_data_packet_converter.h"
24 #include "flutter/lib/ui/window/viewport_metrics.h"
25 #include "flutter/shell/common/platform_message_handler.h"
26 #include "flutter/shell/common/pointer_data_dispatcher.h"
27 #include "flutter/shell/common/vsync_waiter.h"
28 #include "third_party/skia/include/core/SkSize.h"
29 #include "third_party/skia/include/gpu/GrDirectContext.h"
30 
31 namespace flutter {
32 
33 //------------------------------------------------------------------------------
34 /// @brief Platform views are created by the shell on the platform task
35 /// runner. Unless explicitly specified, all platform view methods
36 /// are called on the platform task runner as well. Platform views
37 /// are usually sub-classed on a per platform basis and the bulk of
38 /// the window system integration happens using that subclass. Since
39 /// most platform window toolkits are usually only safe to access on
40 /// a single "main" thread, any interaction that requires access to
41 /// the underlying platform's window toolkit is routed through the
42 /// platform view associated with that shell. This involves
43 /// operations like settings up and tearing down the render surface,
44 /// platform messages, interacting with accessibility features on
45 /// the platform, input events, etc.
46 ///
47 class PlatformView {
48  public:
49  //----------------------------------------------------------------------------
50  /// @brief Used to forward events from the platform view to interested
51  /// subsystems. This forwarding is done by the shell which sets
52  /// itself up as the delegate of the platform view.
53  ///
54  class Delegate {
55  public:
56  using KeyDataResponse = std::function<void(bool)>;
57  //--------------------------------------------------------------------------
58  /// @brief Notifies the delegate that the platform view was created
59  /// with the given render surface. This surface is platform
60  /// (iOS, Android) and client-rendering API (OpenGL, Software,
61  /// Metal, Vulkan) specific. This is usually a sign to the
62  /// rasterizer to set up and begin rendering to that surface.
63  ///
64  /// @param[in] surface The surface
65  ///
66  virtual void OnPlatformViewCreated(std::unique_ptr<Surface> surface) = 0;
67 
68  //--------------------------------------------------------------------------
69  /// @brief Notifies the delegate that the platform view was destroyed.
70  /// This is usually a sign to the rasterizer to suspend
71  /// rendering a previously configured surface and collect any
72  /// intermediate resources.
73  ///
74  virtual void OnPlatformViewDestroyed() = 0;
75 
76  //--------------------------------------------------------------------------
77  /// @brief Notifies the delegate that the specified callback needs to
78  /// be invoked after the rasterizer is done rendering the next
79  /// frame. This callback will be called on the render thread and
80  /// it is caller responsibility to perform any re-threading as
81  /// necessary. Due to the asynchronous nature of rendering in
82  /// Flutter, embedders usually add a placeholder over the
83  /// contents in which Flutter is going to render when Flutter is
84  /// first initialized. This callback may be used as a signal to
85  /// remove that placeholder.
86  ///
87  /// @attention The callback will be invoked on the render thread and not
88  /// the calling thread.
89  ///
90  /// @param[in] closure The callback to execute on the next frame.
91  ///
93  const fml::closure& closure) = 0;
94 
95  //--------------------------------------------------------------------------
96  /// @brief Notifies the delegate the viewport metrics of the platform
97  /// view have been updated. The rasterizer will need to be
98  /// reconfigured to render the frame in the updated viewport
99  /// metrics.
100  ///
101  /// @param[in] metrics The updated viewport metrics.
102  ///
104  const ViewportMetrics& metrics) = 0;
105 
106  //--------------------------------------------------------------------------
107  /// @brief Notifies the delegate that the platform has dispatched a
108  /// platform message from the embedder to the Flutter
109  /// application. This message must be forwarded to the running
110  /// isolate hosted by the engine on the UI thread.
111  ///
112  /// @param[in] message The platform message to dispatch to the running
113  /// root isolate.
114  ///
116  std::unique_ptr<PlatformMessage> message) = 0;
117 
118  //--------------------------------------------------------------------------
119  /// @brief Notifies the delegate that the platform view has encountered
120  /// a pointer event. This pointer event needs to be forwarded to
121  /// the running root isolate hosted by the engine on the UI
122  /// thread.
123  ///
124  /// @param[in] packet The pointer data packet containing multiple pointer
125  /// events.
126  ///
128  std::unique_ptr<PointerDataPacket> packet) = 0;
129 
130  //--------------------------------------------------------------------------
131  /// @brief Notifies the delegate that the platform view has encountered
132  /// a key event. This key event and the callback needs to be
133  /// forwarded to the running root isolate hosted by the engine
134  /// on the UI thread.
135  ///
136  /// @param[in] packet The key data packet containing one key event.
137  /// @param[in] callback Called when the framework has decided whether
138  /// to handle this key data.
139  ///
141  std::unique_ptr<KeyDataPacket> packet,
142  std::function<void(bool /* handled */)> callback) = 0;
143 
144  //--------------------------------------------------------------------------
145  /// @brief Notifies the delegate that the platform view has encountered
146  /// an accessibility related action on the specified node. This
147  /// event must be forwarded to the running root isolate hosted
148  /// by the engine on the UI thread.
149  ///
150  /// @param[in] id The identifier of the accessibility node.
151  /// @param[in] action The accessibility related action performed on the
152  /// node of the specified ID.
153  /// @param[in] args An optional list of argument that apply to the
154  /// specified action.
155  ///
157  int32_t id,
160 
161  //--------------------------------------------------------------------------
162  /// @brief Notifies the delegate that the embedder has expressed an
163  /// opinion about whether the accessibility tree needs to be
164  /// enabled or disabled. This information needs to be forwarded
165  /// to the root isolate running on the UI thread.
166  ///
167  /// @param[in] enabled Whether the accessibility tree is enabled or
168  /// disabled.
169  ///
170  virtual void OnPlatformViewSetSemanticsEnabled(bool enabled) = 0;
171 
172  //--------------------------------------------------------------------------
173  /// @brief Notifies the delegate that the embedder has expressed an
174  /// opinion about the features to enable in the accessibility
175  /// tree.
176  ///
177  /// The engine does not care about the accessibility feature
178  /// flags as all it does is forward this information from the
179  /// embedder to the framework. However, curious readers may
180  /// refer to `AccessibilityFeatures` in `window.dart` for
181  /// currently supported accessibility feature flags.
182  ///
183  /// @param[in] flags The features to enable in the accessibility tree.
184  ///
185  virtual void OnPlatformViewSetAccessibilityFeatures(int32_t flags) = 0;
186 
187  //--------------------------------------------------------------------------
188  /// @brief Notifies the delegate that the embedder has specified a
189  /// texture that it want the rasterizer to composite within the
190  /// Flutter layer tree. All textures must have a unique
191  /// identifier. When the rasterizer encounters an external
192  /// texture within its hierarchy, it gives the embedder a chance
193  /// to update that texture on the raster thread before it
194  /// composites the same on-screen.
195  ///
196  /// @param[in] texture The texture that is being updated by the embedder
197  /// but composited by Flutter in its own hierarchy.
198  ///
199  virtual void OnPlatformViewRegisterTexture(
200  std::shared_ptr<Texture> texture) = 0;
201 
202  //--------------------------------------------------------------------------
203  /// @brief Notifies the delegate that the embedder will no longer
204  /// attempt to composite the specified texture within the layer
205  /// tree. This allows the rasterizer to collect associated
206  /// resources.
207  ///
208  /// @param[in] texture_id The identifier of the texture to unregister. If
209  /// the texture has not been previously registered,
210  /// this call does nothing.
211  ///
212  virtual void OnPlatformViewUnregisterTexture(int64_t texture_id) = 0;
213 
214  //--------------------------------------------------------------------------
215  /// @brief Notifies the delegate that the embedder has updated the
216  /// contents of the texture with the specified identifier.
217  /// Typically, Flutter will only render a frame if there is an
218  /// updated layer tree. However, in cases where the layer tree
219  /// is static but one of the externally composited textures has
220  /// been updated by the embedder, the embedder needs to notify
221  /// the rasterizer to render a new frame. In such cases, the
222  /// existing layer tree may be reused with the frame composited
223  /// with all updated external textures.
224  ///
225  /// @param[in] texture_id The identifier of the texture that has been
226  /// updated.
227  ///
229  int64_t texture_id) = 0;
230 
231  //--------------------------------------------------------------------------
232  /// @brief Loads the dart shared library into the dart VM. When the
233  /// dart library is loaded successfully, the dart future
234  /// returned by the originating loadLibrary() call completes.
235  ///
236  /// The Dart compiler may generate separate shared libraries
237  /// files called 'loading units' when libraries are imported
238  /// as deferred. Each of these shared libraries are identified
239  /// by a unique loading unit id. Callers should open and resolve
240  /// a SymbolMapping from the shared library. The Mappings should
241  /// be moved into this method, as ownership will be assumed by
242  /// the dart root isolate after successful loading and released
243  /// after shutdown of the root isolate. The loading unit may not
244  /// be used after isolate shutdown. If loading fails, the
245  /// mappings will be released.
246  ///
247  /// This method is paired with a RequestDartDeferredLibrary
248  /// invocation that provides the embedder with the loading unit
249  /// id of the deferred library to load.
250  ///
251  ///
252  /// @param[in] loading_unit_id The unique id of the deferred library's
253  /// loading unit.
254  ///
255  /// @param[in] snapshot_data Dart snapshot data of the loading unit's
256  /// shared library.
257  ///
258  /// @param[in] snapshot_data Dart snapshot instructions of the loading
259  /// unit's shared library.
260  ///
261  virtual void LoadDartDeferredLibrary(
262  intptr_t loading_unit_id,
263  std::unique_ptr<const fml::Mapping> snapshot_data,
264  std::unique_ptr<const fml::Mapping> snapshot_instructions) = 0;
265 
266  //--------------------------------------------------------------------------
267  /// @brief Indicates to the dart VM that the request to load a deferred
268  /// library with the specified loading unit id has failed.
269  ///
270  /// The dart future returned by the initiating loadLibrary()
271  /// call will complete with an error.
272  ///
273  /// @param[in] loading_unit_id The unique id of the deferred library's
274  /// loading unit, as passed in by
275  /// RequestDartDeferredLibrary.
276  ///
277  /// @param[in] error_message The error message that will appear in the
278  /// dart Future.
279  ///
280  /// @param[in] transient A transient error is a failure due to
281  /// temporary conditions such as no network.
282  /// Transient errors allow the dart VM to
283  /// re-request the same deferred library and
284  /// and loading_unit_id again. Non-transient
285  /// errors are permanent and attempts to
286  /// re-request the library will instantly
287  /// complete with an error.
288  virtual void LoadDartDeferredLibraryError(intptr_t loading_unit_id,
289  const std::string error_message,
290  bool transient) = 0;
291 
292  //--------------------------------------------------------------------------
293  /// @brief Replaces the asset resolver handled by the engine's
294  /// AssetManager of the specified `type` with
295  /// `updated_asset_resolver`. The matching AssetResolver is
296  /// removed and replaced with `updated_asset_resolvers`.
297  ///
298  /// AssetResolvers should be updated when the existing resolver
299  /// becomes obsolete and a newer one becomes available that
300  /// provides updated access to the same type of assets as the
301  /// existing one. This update process is meant to be performed
302  /// at runtime.
303  ///
304  /// If a null resolver is provided, nothing will be done. If no
305  /// matching resolver is found, the provided resolver will be
306  /// added to the end of the AssetManager resolvers queue. The
307  /// replacement only occurs with the first matching resolver.
308  /// Any additional matching resolvers are untouched.
309  ///
310  /// @param[in] updated_asset_resolver The asset resolver to replace the
311  /// resolver of matching type with.
312  ///
313  /// @param[in] type The type of AssetResolver to update. Only resolvers of
314  /// the specified type will be replaced by the updated
315  /// resolver.
316  ///
317  virtual void UpdateAssetResolverByType(
318  std::unique_ptr<AssetResolver> updated_asset_resolver,
320  };
321 
322  //----------------------------------------------------------------------------
323  /// @brief Creates a platform view with the specified delegate and task
324  /// runner. The base class by itself does not do much but is
325  /// suitable for use in test environments where full platform
326  /// integration may not be necessary. The platform view may only
327  /// be created, accessed and destroyed on the platform task
328  /// runner.
329  ///
330  /// @param delegate The delegate. This is typically the shell.
331  /// @param[in] task_runners The task runners used by this platform view.
332  ///
333  explicit PlatformView(Delegate& delegate, TaskRunners task_runners);
334 
335  //----------------------------------------------------------------------------
336  /// @brief Destroys the platform view. The platform view is owned by the
337  /// shell and will be destroyed by the same on the platform tasks
338  /// runner.
339  ///
340  virtual ~PlatformView();
341 
342  //----------------------------------------------------------------------------
343  /// @brief Invoked by the shell to obtain a platform specific vsync
344  /// waiter. It is optional for platforms to override this method
345  /// and provide a custom vsync waiter because a timer based
346  /// fall-back waiter is used by default. However, it is highly
347  /// recommended that platform provide their own Vsync waiter as
348  /// the timer based fall-back will not render frames aligned with
349  /// vsync boundaries.
350  ///
351  /// @attention If a timer based fall-back is used, a warning is logged to the
352  /// console. In case this method is overridden in a subclass, it
353  /// must return a valid vsync waiter. Returning null will lead to
354  /// internal errors. If a valid vsync waiter cannot be returned,
355  /// subclasses should just call the based class method instead.
356  ///
357  /// @return A vsync waiter. If is an internal error to return a null
358  /// waiter.
359  ///
360  virtual std::unique_ptr<VsyncWaiter> CreateVSyncWaiter();
361 
362  //----------------------------------------------------------------------------
363  /// @brief Used by embedders to dispatch a platform message to a
364  /// running root isolate hosted by the engine. If an isolate is
365  /// not running, the message is dropped. If there is no one on the
366  /// other side listening on the channel, the message is dropped.
367  /// When a platform message is dropped, any response handles
368  /// associated with that message will be dropped as well. All
369  /// users of platform messages must assume that message may not be
370  /// delivered and/or their response handles may not be invoked.
371  /// Platform messages are not buffered.
372  ///
373  /// For embedders that wish to respond to platform message
374  /// directed from the framework to the embedder, the
375  /// `HandlePlatformMessage` method may be overridden.
376  ///
377  /// @see HandlePlatformMessage()
378  ///
379  /// @param[in] message The platform message to deliver to the root isolate.
380  ///
381  void DispatchPlatformMessage(std::unique_ptr<PlatformMessage> message);
382 
383  //----------------------------------------------------------------------------
384  /// @brief Overridden by embedders to perform actions in response to
385  /// platform messages sent from the framework to the embedder.
386  /// Default implementation of this method simply returns an empty
387  /// response.
388  ///
389  /// Embedders that wish to send platform messages to the framework
390  /// may use the `DispatchPlatformMessage` method. This method is
391  /// for messages that go the other way.
392  ///
393  /// @see DispatchPlatformMessage()
394  ///
395  /// @param[in] message The message
396  ///
397  virtual void HandlePlatformMessage(std::unique_ptr<PlatformMessage> message);
398 
399  //----------------------------------------------------------------------------
400  /// @brief Used by embedders to dispatch an accessibility action to a
401  /// running isolate hosted by the engine.
402  ///
403  /// @param[in] id The identifier of the accessibility node on which to
404  /// perform the action.
405  /// @param[in] action The action
406  /// @param[in] args The arguments
407  ///
408  void DispatchSemanticsAction(int32_t id,
411 
412  //----------------------------------------------------------------------------
413  /// @brief Used by embedder to notify the running isolate hosted by the
414  /// engine on the UI thread that the accessibility tree needs to
415  /// be generated.
416  ///
417  /// @attention Subclasses may choose to override this method to perform
418  /// platform specific functions. However, they must call the base
419  /// class method at some point in their implementation.
420  ///
421  /// @param[in] enabled Whether the accessibility tree needs to be generated.
422  ///
423  virtual void SetSemanticsEnabled(bool enabled);
424 
425  //----------------------------------------------------------------------------
426  /// @brief Used by the embedder to specify the features to enable in the
427  /// accessibility tree generated by the isolate. This information
428  /// is forwarded to the root isolate hosted by the engine on the
429  /// UI thread.
430  ///
431  /// The engine does not care about the accessibility feature flags
432  /// as all it does is forward this information from the embedder
433  /// to the framework. However, curious readers may refer to
434  /// `AccessibilityFeatures` in `window.dart` for currently
435  /// supported accessibility feature flags.
436  ///
437  /// @attention Subclasses may choose to override this method to perform
438  /// platform specific functions. However, they must call the base
439  /// class method at some point in their implementation.
440  ///
441  /// @param[in] flags The features to enable in the accessibility tree.
442  ///
443  virtual void SetAccessibilityFeatures(int32_t flags);
444 
445  //----------------------------------------------------------------------------
446  /// @brief Used by the framework to tell the embedder to apply the
447  /// specified semantics node updates. The default implementation
448  /// of this method does nothing.
449  ///
450  /// @see SemanticsNode, SemticsNodeUpdates,
451  /// CustomAccessibilityActionUpdates
452  ///
453  /// @param[in] updates A map with the stable semantics node identifier as
454  /// key and the node properties as the value.
455  /// @param[in] actions A map with the stable semantics node identifier as
456  /// key and the custom node action as the value.
457  ///
458  virtual void UpdateSemantics(SemanticsNodeUpdates updates,
460 
461  //----------------------------------------------------------------------------
462  /// @brief Used by embedders to specify the updated viewport metrics. In
463  /// response to this call, on the raster thread, the rasterizer
464  /// may need to be reconfigured to the updated viewport
465  /// dimensions. On the UI thread, the framework may need to start
466  /// generating a new frame for the updated viewport metrics as
467  /// well.
468  ///
469  /// @param[in] metrics The updated viewport metrics.
470  ///
471  void SetViewportMetrics(const ViewportMetrics& metrics);
472 
473  //----------------------------------------------------------------------------
474  /// @brief Used by embedders to notify the shell that a platform view
475  /// has been created. This notification is used to create a
476  /// rendering surface and pick the client rendering API to use to
477  /// render into this surface. No frames will be scheduled or
478  /// rendered before this call. The surface must remain valid till
479  /// the corresponding call to NotifyDestroyed.
480  ///
481  void NotifyCreated();
482 
483  //----------------------------------------------------------------------------
484  /// @brief Used by embedders to notify the shell that the platform view
485  /// has been destroyed. This notification used to collect the
486  /// rendering surface and all associated resources. Frame
487  /// scheduling is also suspended.
488  ///
489  /// @attention Subclasses may choose to override this method to perform
490  /// platform specific functions. However, they must call the base
491  /// class method at some point in their implementation.
492  ///
493  virtual void NotifyDestroyed();
494 
495  //----------------------------------------------------------------------------
496  /// @brief Used by the shell to obtain a Skia GPU context that is capable
497  /// of operating on the IO thread. The context must be in the same
498  /// share-group as the Skia GPU context used on the render thread.
499  /// This context will always be used on the IO thread. Because it
500  /// is in the same share-group as the separate render thread
501  /// context, any GPU resources uploaded in this context will be
502  /// visible to the render thread context (synchronization of GPU
503  /// resources is managed by Skia).
504  ///
505  /// If such context cannot be created on the IO thread, callers
506  /// may return `nullptr`. This will mean that all texture uploads
507  /// will be queued onto the render thread which will cause
508  /// performance issues. When this context is `nullptr`, an error
509  /// is logged to the console. It is highly recommended that all
510  /// platforms provide a resource context.
511  ///
512  /// @attention Unlike all other methods on the platform view, this will be
513  /// called on IO task runner.
514  ///
515  /// @return The Skia GPU context that is in the same share-group as the
516  /// main render thread GPU context. May be `nullptr` in case such
517  /// a context cannot be created.
518  ///
519  virtual sk_sp<GrDirectContext> CreateResourceContext() const;
520 
521  //----------------------------------------------------------------------------
522  /// @brief Used by the shell to notify the embedder that the resource
523  /// context previously obtained via a call to
524  /// `CreateResourceContext()` is being collected. The embedder is
525  /// free to collect an platform specific resources associated with
526  /// this context.
527  ///
528  /// @attention Unlike all other methods on the platform view, this will be
529  /// called on IO task runner.
530  ///
531  virtual void ReleaseResourceContext() const;
532 
533  //--------------------------------------------------------------------------
534  /// @brief Returns a platform-specific PointerDataDispatcherMaker so the
535  /// `Engine` can construct the PointerDataPacketDispatcher based
536  /// on platforms.
538 
539  //----------------------------------------------------------------------------
540  /// @brief Returns a weak pointer to the platform view. Since the
541  /// platform view may only be created, accessed and destroyed
542  /// on the platform thread, any access to the platform view
543  /// from a non-platform task runner needs a weak pointer to
544  /// the platform view along with a reference to the platform
545  /// task runner. A task must be posted to the platform task
546  /// runner with the weak pointer captured in the same. The
547  /// platform view method may only be called in the posted task
548  /// once the weak pointer validity has been checked. This
549  /// method is used by callers to obtain that weak pointer.
550  ///
551  /// @return The weak pointer to the platform view.
552  ///
554 
555  //----------------------------------------------------------------------------
556  /// @brief Gives embedders a chance to react to a "cold restart" of the
557  /// running isolate. The default implementation of this method
558  /// does nothing.
559  ///
560  /// While a "hot restart" patches a running isolate, a "cold
561  /// restart" restarts the root isolate in a running shell.
562  ///
563  virtual void OnPreEngineRestart() const;
564 
565  //----------------------------------------------------------------------------
566  /// @brief Sets a callback that gets executed when the rasterizer renders
567  /// the next frame. Due to the asynchronous nature of
568  /// rendering in Flutter, embedders usually add a placeholder
569  /// over the contents in which Flutter is going to render when
570  /// Flutter is first initialized. This callback may be used as
571  /// a signal to remove that placeholder. The callback is
572  /// executed on the render task runner and not the platform
573  /// task runner. It is the embedder's responsibility to
574  /// re-thread as necessary.
575  ///
576  /// @attention The callback is executed on the render task runner and not the
577  /// platform task runner. Embedders must re-thread as necessary.
578  ///
579  /// @param[in] closure The callback to execute on the render thread when the
580  /// next frame gets rendered.
581  ///
583 
584  //----------------------------------------------------------------------------
585  /// @brief Dispatches pointer events from the embedder to the
586  /// framework. Each pointer data packet may contain multiple
587  /// pointer input events. Each call to this method wakes up
588  /// the UI thread.
589  ///
590  /// @param[in] packet The pointer data packet to dispatch to the framework.
591  ///
592  void DispatchPointerDataPacket(std::unique_ptr<PointerDataPacket> packet);
593 
594  //----------------------------------------------------------------------------
595  /// @brief Dispatches key events from the embedder to the framework. Each
596  /// key data packet contains one physical event and multiple
597  /// logical key events. Each call to this method wakes up the UI
598  /// thread.
599  ///
600  /// @param[in] packet The key data packet to dispatch to the framework.
601  ///
602  void DispatchKeyDataPacket(std::unique_ptr<KeyDataPacket> packet,
604 
605  //--------------------------------------------------------------------------
606  /// @brief Used by the embedder to specify a texture that it wants the
607  /// rasterizer to composite within the Flutter layer tree. All
608  /// textures must have a unique identifier. When the
609  /// rasterizer encounters an external texture within its
610  /// hierarchy, it gives the embedder a chance to update that
611  /// texture on the raster thread before it composites the same
612  /// on-screen.
613  ///
614  /// @attention This method must only be called once per texture. When the
615  /// texture is updated, calling `MarkTextureFrameAvailable`
616  /// with the specified texture identifier is sufficient to
617  /// make Flutter re-render the frame with the updated texture
618  /// composited in-line.
619  ///
620  /// @see UnregisterTexture, MarkTextureFrameAvailable
621  ///
622  /// @param[in] texture The texture that is being updated by the embedder
623  /// but composited by Flutter in its own hierarchy.
624  ///
625  void RegisterTexture(std::shared_ptr<flutter::Texture> texture);
626 
627  //--------------------------------------------------------------------------
628  /// @brief Used by the embedder to notify the rasterizer that it will
629  /// no
630  /// longer attempt to composite the specified texture within
631  /// the layer tree. This allows the rasterizer to collect
632  /// associated resources.
633  ///
634  /// @attention This call must only be called once per texture identifier.
635  ///
636  /// @see RegisterTexture, MarkTextureFrameAvailable
637  ///
638  /// @param[in] texture_id The identifier of the texture to unregister. If
639  /// the texture has not been previously registered,
640  /// this call does nothing.
641  ///
642  void UnregisterTexture(int64_t texture_id);
643 
644  //--------------------------------------------------------------------------
645  /// @brief Used by the embedder to notify the rasterizer that the context
646  /// of the previously registered texture have been updated.
647  /// Typically, Flutter will only render a frame if there is an
648  /// updated layer tree. However, in cases where the layer tree
649  /// is static but one of the externally composited textures
650  /// has been updated by the embedder, the embedder needs to
651  /// notify the rasterizer to render a new frame. In such
652  /// cases, the existing layer tree may be reused with the
653  /// frame re-composited with all updated external textures.
654  /// Unlike the calls to register and unregister the texture,
655  /// this call must be made each time a new texture frame is
656  /// available.
657  ///
658  /// @see RegisterTexture, UnregisterTexture
659  ///
660  /// @param[in] texture_id The identifier of the texture that has been
661  /// updated.
662  ///
664 
665  //--------------------------------------------------------------------------
666  /// @brief Directly invokes platform-specific APIs to compute the
667  /// locale the platform would have natively resolved to.
668  ///
669  /// @param[in] supported_locale_data The vector of strings that represents
670  /// the locales supported by the app.
671  /// Each locale consists of three
672  /// strings: languageCode, countryCode,
673  /// and scriptCode in that order.
674  ///
675  /// @return A vector of 3 strings languageCode, countryCode, and
676  /// scriptCode that represents the locale selected by the
677  /// platform. Empty strings mean the value was unassigned. Empty
678  /// vector represents a null locale.
679  ///
680  virtual std::unique_ptr<std::vector<std::string>>
682  const std::vector<std::string>& supported_locale_data);
683 
684  virtual std::shared_ptr<ExternalViewEmbedder> CreateExternalViewEmbedder();
685 
686  //--------------------------------------------------------------------------
687  /// @brief Invoked when the dart VM requests that a deferred library
688  /// be loaded. Notifies the engine that the deferred library
689  /// identified by the specified loading unit id should be
690  /// downloaded and loaded into the Dart VM via
691  /// `LoadDartDeferredLibrary`
692  ///
693  /// Upon encountering errors or otherwise failing to load a
694  /// loading unit with the specified id, the failure should be
695  /// directly reported to dart by calling
696  /// `LoadDartDeferredLibraryFailure` to ensure the waiting dart
697  /// future completes with an error.
698  ///
699  /// @param[in] loading_unit_id The unique id of the deferred library's
700  /// loading unit. This id is to be passed
701  /// back into LoadDartDeferredLibrary
702  /// in order to identify which deferred
703  /// library to load.
704  ///
705  virtual void RequestDartDeferredLibrary(intptr_t loading_unit_id);
706 
707  //--------------------------------------------------------------------------
708  /// @brief Loads the Dart shared library into the Dart VM. When the
709  /// Dart library is loaded successfully, the Dart future
710  /// returned by the originating loadLibrary() call completes.
711  ///
712  /// The Dart compiler may generate separate shared libraries
713  /// files called 'loading units' when libraries are imported
714  /// as deferred. Each of these shared libraries are identified
715  /// by a unique loading unit id. Callers should open and resolve
716  /// a SymbolMapping from the shared library. The Mappings should
717  /// be moved into this method, as ownership will be assumed by the
718  /// dart isolate after successful loading and released after
719  /// shutdown of the dart isolate. If loading fails, the mappings
720  /// will naturally go out of scope.
721  ///
722  /// This method is paired with a RequestDartDeferredLibrary
723  /// invocation that provides the embedder with the loading unit id
724  /// of the deferred library to load.
725  ///
726  ///
727  /// @param[in] loading_unit_id The unique id of the deferred library's
728  /// loading unit, as passed in by
729  /// RequestDartDeferredLibrary.
730  ///
731  /// @param[in] snapshot_data Dart snapshot data of the loading unit's
732  /// shared library.
733  ///
734  /// @param[in] snapshot_data Dart snapshot instructions of the loading
735  /// unit's shared library.
736  ///
737  virtual void LoadDartDeferredLibrary(
738  intptr_t loading_unit_id,
739  std::unique_ptr<const fml::Mapping> snapshot_data,
740  std::unique_ptr<const fml::Mapping> snapshot_instructions);
741 
742  //--------------------------------------------------------------------------
743  /// @brief Indicates to the dart VM that the request to load a deferred
744  /// library with the specified loading unit id has failed.
745  ///
746  /// The dart future returned by the initiating loadLibrary() call
747  /// will complete with an error.
748  ///
749  /// @param[in] loading_unit_id The unique id of the deferred library's
750  /// loading unit, as passed in by
751  /// RequestDartDeferredLibrary.
752  ///
753  /// @param[in] error_message The error message that will appear in the
754  /// dart Future.
755  ///
756  /// @param[in] transient A transient error is a failure due to
757  /// temporary conditions such as no network.
758  /// Transient errors allow the dart VM to
759  /// re-request the same deferred library and
760  /// and loading_unit_id again. Non-transient
761  /// errors are permanent and attempts to
762  /// re-request the library will instantly
763  /// complete with an error.
764  ///
765  virtual void LoadDartDeferredLibraryError(intptr_t loading_unit_id,
766  const std::string error_message,
767  bool transient);
768 
769  //--------------------------------------------------------------------------
770  /// @brief Replaces the asset resolver handled by the engine's
771  /// AssetManager of the specified `type` with
772  /// `updated_asset_resolver`. The matching AssetResolver is
773  /// removed and replaced with `updated_asset_resolvers`.
774  ///
775  /// AssetResolvers should be updated when the existing resolver
776  /// becomes obsolete and a newer one becomes available that
777  /// provides updated access to the same type of assets as the
778  /// existing one. This update process is meant to be performed
779  /// at runtime.
780  ///
781  /// If a null resolver is provided, nothing will be done. If no
782  /// matching resolver is found, the provided resolver will be
783  /// added to the end of the AssetManager resolvers queue. The
784  /// replacement only occurs with the first matching resolver.
785  /// Any additional matching resolvers are untouched.
786  ///
787  /// @param[in] updated_asset_resolver The asset resolver to replace the
788  /// resolver of matching type with.
789  ///
790  /// @param[in] type The type of AssetResolver to update. Only resolvers of
791  /// the specified type will be replaced by the updated
792  /// resolver.
793  ///
794  virtual void UpdateAssetResolverByType(
795  std::unique_ptr<AssetResolver> updated_asset_resolver,
797 
798  //--------------------------------------------------------------------------
799  /// @brief Creates an object that produces surfaces suitable for raster
800  /// snapshotting. The rasterizer will request this surface if no
801  /// on screen surface is currently available when an application
802  /// requests a snapshot, e.g. if `Scene.toImage` or
803  /// `Picture.toImage` are called while the application is in the
804  /// background.
805  ///
806  /// Not all backends support this kind of surface usage, and the
807  /// default implementation returns nullptr. Platforms should
808  /// override this if they can support GPU operations in the
809  /// background and support GPU resource context usage.
810  ///
811  virtual std::unique_ptr<SnapshotSurfaceProducer>
813 
814  //--------------------------------------------------------------------------
815  /// @brief Specifies a delegate that will receive PlatformMessages from
816  /// Flutter to the host platform.
817  ///
818  /// @details If this returns `null` that means PlatformMessages should be sent
819  /// to the PlatformView. That is to protect legacy behavior, any embedder
820  /// that wants to support executing Platform Channel handlers on background
821  /// threads should be returing a thread-safe PlatformMessageHandler instead.
822  virtual std::shared_ptr<PlatformMessageHandler> GetPlatformMessageHandler()
823  const;
824 
825  protected:
828 
830  SkISize size_;
832 
833  // This is the only method called on the raster task runner.
834  virtual std::unique_ptr<Surface> CreateRenderingSurface();
835 
836  private:
838 };
839 
840 } // namespace flutter
841 
842 #endif // COMMON_PLATFORM_VIEW_H_
G_BEGIN_DECLS FlValue * args
virtual void OnPreEngineRestart() const
Gives embedders a chance to react to a "cold restart" of the running isolate. The default implementat...
KeyCallType type
fml::WeakPtrFactory< PlatformView > weak_factory_
G_BEGIN_DECLS FlTexture * texture
void MarkTextureFrameAvailable(int64_t texture_id)
Used by the embedder to notify the rasterizer that the context of the previously registered texture h...
void DispatchSemanticsAction(int32_t id, SemanticsAction action, fml::MallocMapping args)
Used by embedders to dispatch an accessibility action to a running isolate hosted by the engine...
virtual std::unique_ptr< std::vector< std::string > > ComputePlatformResolvedLocales(const std::vector< std::string > &supported_locale_data)
Directly invokes platform-specific APIs to compute the locale the platform would have natively resolv...
virtual std::shared_ptr< PlatformMessageHandler > GetPlatformMessageHandler() const
Specifies a delegate that will receive PlatformMessages from Flutter to the host platform.
const TaskRunners task_runners_
virtual void OnPlatformViewSetSemanticsEnabled(bool enabled)=0
Notifies the delegate that the embedder has expressed an opinion about whether the accessibility tree...
virtual std::unique_ptr< VsyncWaiter > CreateVSyncWaiter()
Invoked by the shell to obtain a platform specific vsync waiter. It is optional for platforms to over...
virtual void OnPlatformViewDispatchPlatformMessage(std::unique_ptr< PlatformMessage > message)=0
Notifies the delegate that the platform has dispatched a platform message from the embedder to the Fl...
virtual void SetAccessibilityFeatures(int32_t flags)
Used by the embedder to specify the features to enable in the accessibility tree generated by the iso...
virtual void OnPlatformViewMarkTextureFrameAvailable(int64_t texture_id)=0
Notifies the delegate that the embedder has updated the contents of the texture with the specified id...
PlatformView(Delegate &delegate, TaskRunners task_runners)
Creates a platform view with the specified delegate and task runner. The base class by itself does no...
Dart_NativeFunction function
Definition: fuchsia.cc:51
std::unordered_map< int32_t, SemanticsNode > SemanticsNodeUpdates
int64_t texture_id
virtual void UpdateSemantics(SemanticsNodeUpdates updates, CustomAccessibilityActionUpdates actions)
Used by the framework to tell the embedder to apply the specified semantics node updates. The default implementation of this method does nothing.
std::function< std::unique_ptr< PointerDataDispatcher >(PointerDataDispatcher::Delegate &)> PointerDataDispatcherMaker
Signature for constructing PointerDataDispatcher.
virtual std::unique_ptr< SnapshotSurfaceProducer > CreateSnapshotSurfaceProducer()
Creates an object that produces surfaces suitable for raster snapshotting. The rasterizer will reques...
Platform views are created by the shell on the platform task runner. Unless explicitly specified...
Definition: platform_view.h:47
FlKeyEvent FlKeyResponderAsyncCallback callback
void SetNextFrameCallback(const fml::closure &closure)
Sets a callback that gets executed when the rasterizer renders the next frame. Due to the asynchronou...
void DispatchPointerDataPacket(std::unique_ptr< PointerDataPacket > packet)
Dispatches pointer events from the embedder to the framework. Each pointer data packet may contain mu...
virtual void OnPlatformViewRegisterTexture(std::shared_ptr< Texture > texture)=0
Notifies the delegate that the embedder has specified a texture that it want the rasterizer to compos...
virtual ~PlatformView()
Destroys the platform view. The platform view is owned by the shell and will be destroyed by the same...
AssetResolverType
Identifies the type of AssetResolver an instance is.
virtual PointerDataDispatcherMaker GetDispatcherMaker()
Returns a platform-specific PointerDataDispatcherMaker so the Engine can construct the PointerDataPac...
std::function< void()> closure
Definition: closure.h:14
virtual void ReleaseResourceContext() const
Used by the shell to notify the embedder that the resource context previously obtained via a call to ...
virtual void LoadDartDeferredLibraryError(intptr_t loading_unit_id, const std::string error_message, bool transient)=0
Indicates to the dart VM that the request to load a deferred library with the specified loading unit ...
virtual void SetSemanticsEnabled(bool enabled)
Used by embedder to notify the running isolate hosted by the engine on the UI thread that the accessi...
void DispatchPlatformMessage(std::unique_ptr< PlatformMessage > message)
Used by embedders to dispatch a platform message to a running root isolate hosted by the engine...
void DispatchKeyDataPacket(std::unique_ptr< KeyDataPacket > packet, Delegate::KeyDataResponse callback)
Dispatches key events from the embedder to the framework. Each key data packet contains one physical ...
PlatformView::Delegate & delegate_
virtual void RequestDartDeferredLibrary(intptr_t loading_unit_id)
Invoked when the dart VM requests that a deferred library be loaded. Notifies the engine that the def...
SemanticsAction action
virtual void OnPlatformViewDispatchSemanticsAction(int32_t id, SemanticsAction action, fml::MallocMapping args)=0
Notifies the delegate that the platform view has encountered an accessibility related action on the s...
virtual sk_sp< GrDirectContext > CreateResourceContext() const
Used by the shell to obtain a Skia GPU context that is capable of operating on the IO thread...
virtual void UpdateAssetResolverByType(std::unique_ptr< AssetResolver > updated_asset_resolver, AssetResolver::AssetResolverType type)=0
Replaces the asset resolver handled by the engine&#39;s AssetManager of the specified type with updated_a...
virtual void LoadDartDeferredLibrary(intptr_t loading_unit_id, std::unique_ptr< const fml::Mapping > snapshot_data, std::unique_ptr< const fml::Mapping > snapshot_instructions)=0
Loads the dart shared library into the dart VM. When the dart library is loaded successfully, the dart future returned by the originating loadLibrary() call completes.
void SetViewportMetrics(const ViewportMetrics &metrics)
Used by embedders to specify the updated viewport metrics. In response to this call, on the raster thread, the rasterizer may need to be reconfigured to the updated viewport dimensions. On the UI thread, the framework may need to start generating a new frame for the updated viewport metrics as well.
virtual void OnPlatformViewDestroyed()=0
Notifies the delegate that the platform view was destroyed. This is usually a sign to the rasterizer ...
PointerDataPacketConverter pointer_data_packet_converter_
virtual void OnPlatformViewCreated(std::unique_ptr< Surface > surface)=0
Notifies the delegate that the platform view was created with the given render surface. This surface is platform (iOS, Android) and client-rendering API (OpenGL, Software, Metal, Vulkan) specific. This is usually a sign to the rasterizer to set up and begin rendering to that surface.
virtual void OnPlatformViewSetAccessibilityFeatures(int32_t flags)=0
Notifies the delegate that the embedder has expressed an opinion about the features to enable in the ...
void NotifyCreated()
Used by embedders to notify the shell that a platform view has been created. This notification is use...
virtual void OnPlatformViewDispatchPointerDataPacket(std::unique_ptr< PointerDataPacket > packet)=0
Notifies the delegate that the platform view has encountered a pointer event. This pointer event need...
fml::WeakPtr< PlatformView > GetWeakPtr() const
Returns a weak pointer to the platform view. Since the platform view may only be created, accessed and destroyed on the platform thread, any access to the platform view from a non-platform task runner needs a weak pointer to the platform view along with a reference to the platform task runner. A task must be posted to the platform task runner with the weak pointer captured in the same. The platform view method may only be called in the posted task once the weak pointer validity has been checked. This method is used by callers to obtain that weak pointer.
virtual void NotifyDestroyed()
Used by embedders to notify the shell that the platform view has been destroyed. This notification us...
virtual std::unique_ptr< Surface > CreateRenderingSurface()
void RegisterTexture(std::shared_ptr< flutter::Texture > texture)
Used by the embedder to specify a texture that it wants the rasterizer to composite within the Flutte...
A Mapping like NonOwnedMapping, but uses Free as its release proc.
Definition: mapping.h:129
std::function< void(bool)> KeyDataResponse
Definition: platform_view.h:56
std::unordered_map< int32_t, CustomAccessibilityAction > CustomAccessibilityActionUpdates
virtual void OnPlatformViewSetNextFrameCallback(const fml::closure &closure)=0
Notifies the delegate that the specified callback needs to be invoked after the rasterizer is done re...
#define FML_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: macros.h:27
Used to forward events from the platform view to interested subsystems. This forwarding is done by th...
Definition: platform_view.h:54
void UnregisterTexture(int64_t texture_id)
Used by the embedder to notify the rasterizer that it will no longer attempt to composite the specifi...
virtual void HandlePlatformMessage(std::unique_ptr< PlatformMessage > message)
Overridden by embedders to perform actions in response to platform messages sent from the framework t...
virtual void OnPlatformViewUnregisterTexture(int64_t texture_id)=0
Notifies the delegate that the embedder will no longer attempt to composite the specified texture wit...
virtual void OnPlatformViewSetViewportMetrics(const ViewportMetrics &metrics)=0
Notifies the delegate the viewport metrics of the platform view have been updated. The rasterizer will need to be reconfigured to render the frame in the updated viewport metrics.
virtual void OnPlatformViewDispatchKeyDataPacket(std::unique_ptr< KeyDataPacket > packet, std::function< void(bool)> callback)=0
Notifies the delegate that the platform view has encountered a key event. This key event and the call...
DEF_SWITCHES_START snapshot asset Path to the directory containing the four files specified by VmSnapshotInstructions and IsolateSnapshotInstructions vm snapshot The VM instructions snapshot that will be memory mapped as read and executable SnapshotAssetPath must be present isolate snapshot The isolate instructions snapshot that will be memory mapped as read and executable SnapshotAssetPath must be present icu symbol Prefix for the symbols representing ICU data linked into the Flutter library dart flags
Definition: switches.h:66
virtual std::shared_ptr< ExternalViewEmbedder > CreateExternalViewEmbedder()