From 340ddedbfa29fb65f97fc91dc0eb769218812c99 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 29 Apr 2026 06:16:02 -0700 Subject: [PATCH 1/6] Updating the hcpp docs --- .../android/platform-views.md | 109 ++++++++++++++---- 1 file changed, 88 insertions(+), 21 deletions(-) diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index 37b780ea3de..c83190953e8 100644 --- a/src/content/platform-integration/android/platform-views.md +++ b/src/content/platform-integration/android/platform-views.md @@ -1,7 +1,8 @@ --- 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,8 +11,8 @@ 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 @@ -26,35 +27,97 @@ see [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) -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) 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) +* `-` 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: +## [Hybrid Composition++ (HCPP)](#hcpp) + +:::note +This feature is experimental and 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. + +### Opting 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: ## On the Dart side @@ -115,7 +178,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 +221,7 @@ use the following instructions: } ``` -For more information, see the API docs for: +For more information, visit the API docs for: * [`AndroidView`][] @@ -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,24 +481,28 @@ android { } } ``` -### Surface Views +### Surface views -Handling SurfaceViews is problematic for Flutter and should be avoided when possible. +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 PlatformView 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 or one of its parent views. -[`AndroidViewSurface`]: {{site.api}}/flutter/widgets/AndroidViewSurface-class.html +[`AndroidViewSurface`]: +{{site.api}}/flutter/widgets/AndroidViewSurface-class.html ### Issues -[Existing Platform View issues](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views%22) +[Existing PlatformView issues][] {% render "docs/platform-view-perf.md", site: site %} + +[Existing PlatformView issues]: {{site.github}}/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views%22 From 19634434096366d48d96028169a934b9bf55a470 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 29 Apr 2026 06:33:06 -0700 Subject: [PATCH 2/6] tweak --- .../platform-integration/android/platform-views.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index c83190953e8..eb4b511e526 100644 --- a/src/content/platform-integration/android/platform-views.md +++ b/src/content/platform-integration/android/platform-views.md @@ -69,8 +69,9 @@ 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. + +* **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, @@ -490,7 +491,7 @@ possible. Certain Android Views don't invalidate themselves when their content changes. Some example views include `SurfaceView` and `SurfaceTexture`. -When your PlatformView 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 @@ -501,8 +502,8 @@ or one of its parent views. ### Issues -[Existing PlatformView issues][] +[Existing Platform View issues][] {% render "docs/platform-view-perf.md", site: site %} -[Existing PlatformView issues]: {{site.github}}/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views%22 +[Existing Platform View issues]: {{site.github}}/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views%22 From 34e9ef706477e8efcc347a5f6eb3e7543827c09c Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 29 Apr 2026 06:39:15 -0700 Subject: [PATCH 3/6] tweak tweak --- src/content/platform-integration/android/platform-views.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index eb4b511e526..b90ddfc7833 100644 --- a/src/content/platform-integration/android/platform-views.md +++ b/src/content/platform-integration/android/platform-views.md @@ -52,7 +52,7 @@ 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 +* `-` 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. @@ -497,8 +497,7 @@ manually invalidate the view after they have been drawn to Manual view invalidation is done by calling `invalidate` on the View or one of its parent views. -[`AndroidViewSurface`]: -{{site.api}}/flutter/widgets/AndroidViewSurface-class.html +[`AndroidViewSurface`]: {{site.api}}/flutter/widgets/AndroidViewSurface-class.html ### Issues @@ -506,4 +505,4 @@ or one of its parent views. {% 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%22 +[Existing Platform View issues]: {{site.github}}/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+platform-views From 20ed5673b348b459e875678275f7e32adaa2089e Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 29 Apr 2026 06:45:57 -0700 Subject: [PATCH 4/6] Fixing front matter --- src/content/platform-integration/android/platform-views.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index b90ddfc7833..34cfd4450d0 100644 --- a/src/content/platform-integration/android/platform-views.md +++ b/src/content/platform-integration/android/platform-views.md @@ -1,8 +1,7 @@ --- 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. --- From 883530e31deb700856df3471fc383fb432f32d10 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 29 Apr 2026 10:50:20 -0700 Subject: [PATCH 5/6] Incorporating Jenn's feedback --- .../android/platform-views.md | 37 ++++++++----------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index 34cfd4450d0..6e97205d148 100644 --- a/src/content/platform-integration/android/platform-views.md +++ b/src/content/platform-integration/android/platform-views.md @@ -42,20 +42,6 @@ SurfaceFlinger composes the Flutter content and the 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) - -Platform Views are rendered into a 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 (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. - ## [Hybrid Composition++ (HCPP)](#hcpp) :::note @@ -77,7 +63,7 @@ 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. -### Opting In +### Opting 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 @@ -118,6 +104,19 @@ You can enable HCPP using one of the following methods: when all four of these layers intersect. To create a platform view on Android, use the following steps: +## [Texture Layer](#texturelayerhybridcomposition) (or Texture Layer Hybrid Composition) + +Platform Views are rendered into a 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 (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. ## On the Dart side @@ -410,8 +409,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 @@ -481,11 +479,6 @@ android { } } ``` -### Surface views - -Handling SurfaceViews is problematic for Flutter and should be avoided when -possible. - ### Manual view invalidation Certain Android Views don't invalidate themselves when their content changes. From 2cf1f89d4a86a438be15a561630791d3e9266fd8 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 29 Apr 2026 11:24:45 -0700 Subject: [PATCH 6/6] Fixed malformed anchors --- .../android/platform-views.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/src/content/platform-integration/android/platform-views.md b/src/content/platform-integration/android/platform-views.md index 6e97205d148..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. --- @@ -18,9 +20,9 @@ directly inside your Flutter app. 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 @@ -29,8 +31,7 @@ see [Hosting native macOS views][]. 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. @@ -42,10 +43,10 @@ SurfaceFlinger composes the Flutter content and the platform views. * `-` Certain transformations that can be applied to Flutter widgets won't work when applied to platform views. -## [Hybrid Composition++ (HCPP)](#hcpp) +## Hybrid Composition++ (HCPP) {: #hcpp } :::note -This feature is experimental and available starting from Flutter 3.44. +This feature is experimental and is available starting from Flutter 3.44. ::: HCPP is the latest hybrid composition strategy, @@ -63,7 +64,7 @@ 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. -### Opting in +### 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 @@ -95,7 +96,7 @@ You can enable HCPP using one of the following methods: android:value="true" /> ``` -### Limitations and Known Issues +### Limitations and known issues * **Complex Overlay Stacking**: Transparent platform views won't display correctly @@ -103,8 +104,9 @@ You can enable HCPP using one of the following methods: 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) (or Texture Layer Hybrid Composition) +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 (using the texture). @@ -479,6 +481,7 @@ android { } } ``` + ### Manual view invalidation Certain Android Views don't invalidate themselves when their content changes.