diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index 37b780ea3de..ed0eb30ed37 100644 --- a/src/content/platform-integration/android/platform-views.md +++ b/src/content/platform-integration/android/platform-views.md @@ -1,7 +1,9 @@ --- title: Hosting native Android views in your Flutter app with Platform Views shortTitle: Android platform-views -description: Learn how to host native Android views in your Flutter app with Platform Views. +description: >- + Learn how to host native Android views in your + Flutter app with Platform Views. --- @@ -10,52 +12,114 @@ Platform views allow you to embed native views in a Flutter app, so you can apply transforms, clips, and opacity to the native view from Dart. -This allows you, for example, to use the native -Google Maps from the Android SDK +This allows you, for example, +to use the native Google Maps from the Android SDK directly inside your Flutter app. :::note This page discusses how to host your own native Android views within a Flutter app. If you'd like to embed native iOS views in your Flutter app, -see [Hosting native iOS views][]. -If you'd like to embed native macOS views in your Flutter app, -see [Hosting native macOS views][]. +visit [Hosting native iOS views][]. +To embed native macOS views in your Flutter app, +visit [Hosting native macOS views][]. ::: [Hosting native iOS views]: /platform-integration/ios/platform-views [Hosting native macOS views]: /platform-integration/macos/platform-views -Platform Views on Android have two implementations. They come with tradeoffs -both in terms of performance and fidelity. -Platform views require Android API 23+. +Platform Views on Android have several implementations. +They come with tradeoffs both in terms of performance and fidelity. -## [Hybrid Composition](#hybrid-composition) +## Hybrid composition {: #hybrid-composition } -Platform Views are rendered as they are normally. Flutter content is rendered into a texture. +Platform Views are rendered as they are normally. +Flutter content is rendered into a texture. SurfaceFlinger composes the Flutter content and the platform views. * `+` best performance and fidelity of Android views. * `-` Flutter performance suffers. * `-` FPS of application will be lower. -* `-` Certain transformations that can be applied to Flutter widgets will not work when applied to platform views. +* `-` Certain transformations that can be applied to Flutter widgets + won't work when applied to platform views. -## [Texture Layer](#texturelayerhybridcomposition) (or Texture Layer Hybrid Composition) +## Hybrid Composition++ (HCPP) {: #hcpp } + +:::note +This feature is experimental and is available starting from Flutter 3.44. +::: + +HCPP is the latest hybrid composition strategy, +designed to solve compositing performance and synchronization issues +seen in the original Hybrid Composition mode. +It is currently available as an opt-in feature. + +### Requirements + +* **Android API 34 or later**: Required for native transaction + synchronization capabilities. +* **Vulkan Rendering**: The device must be capable of rendering with Vulkan. + +If these requirements are not met on the end-user device, +Flutter will automatically fall back to the existing platform view strategy +configured for the app. + +### Opt in + +Because HCPP acts as a global upgrade for how platform views are backed, +it's enabled through configuration rather than standard Dart initialization methods +(`initAndroidView`, and so on). + +You can enable HCPP using one of the following methods: + +1. **Command Line Flag (Run/Test)**: + Pass the `--enable-hcpp` flag to your `flutter run` or `flutter test` command: + + ```bash + flutter run --enable-hcpp + ``` + +:::note + This flag is intended for local execution and testing. + It **can't** be passed to the `flutter build` commands. + For release builds, use the manifest configuration + as shown in the next step. +::: + +2. **AndroidManifest.xml**: + Include a `` tag inside the `` block of your + `AndroidManifest.xml`: + + ```xml + + ``` + +### Limitations and known issues + +* **Complex Overlay Stacking**: + Transparent platform views won't display correctly + in layout stacks structured as: + Flutter canvas -> Platform View -> Overlay -> Transparent Platform View, + when all four of these layers intersect. + +To create a platform view on Android, use the following steps. + +## Texture layer { #texturelayerhybridcomposition } Platform Views are rendered into a texture. -Flutter draws the platform views (via the texture). +Flutter draws the platform views (using the texture). Flutter content is rendered directly into a Surface. * `+` good performance for Android Views * `+` best performance for Flutter rendering. * `+` all transformations work correctly. -* `-` quick scrolling (e.g. a web view) will be janky -* `-` SurfaceViews are problematic in this mode and will be moved into a virtual display (breaking a11y) +* `-` quick scrolling (such as a web view) will be janky +* `-` SurfaceViews are problematic in this mode and will be moved into a virtual +display (breaking a11y) * `-` Text magnifier will break unless Flutter is rendered into a TextureView. -To create a platform view on Android, -use the following steps: - ## On the Dart side On the Dart side, create a `Widget` @@ -115,7 +179,7 @@ use the following instructions: } ``` -For more information, see the API docs for: +For more information, visit the API docs for: * [`PlatformViewLink`][] * [`AndroidViewSurface`][] @@ -158,7 +222,7 @@ use the following instructions: } ``` -For more information, see the API docs for: +For more information, visit the API docs for: * [`AndroidView`][] @@ -347,8 +411,7 @@ class NativeViewFactory extends PlatformViewFactory { Finally, register the platform view. You can do this in an app or a plugin. -For app registration, -modify the app's main activity +For app registration, modify the app's main activity (for example, `MainActivity.java`): ```java @@ -395,7 +458,7 @@ public class PlatformViewPlugin implements FlutterPlugin { -For more information, see the API docs for: +For more information, visit the API docs for: * [`FlutterPlugin`][] * [`PlatformViewRegistry`][] @@ -418,15 +481,12 @@ android { } } ``` -### Surface Views - -Handling SurfaceViews is problematic for Flutter and should be avoided when possible. ### Manual view invalidation -Certain Android Views do not invalidate themselves when their content changes. +Certain Android Views don't invalidate themselves when their content changes. Some example views include `SurfaceView` and `SurfaceTexture`. -When your Platform View includes these views you are required to +When your Platform View includes these views, you are required to manually invalidate the view after they have been drawn to (or more specifically: after the swap chain is flipped). Manual view invalidation is done by calling `invalidate` on the View @@ -436,6 +496,8 @@ or one of its parent views. ### Issues -[Existing Platform View issues](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views%22) +[Existing Platform View issues][] {% render "docs/platform-view-perf.md", site: site %} + +[Existing Platform View issues]: {{site.github}}/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views