Add notes on HCPP to Android-Platform-Views.md (#183859)

gmackall · mackall-work · web-flow · commit d1d1fbc45233 · 2026-03-26T04:59:03.000Z
Adds notes, including how to opt in, what opt in does, and limitations.

---------

Co-authored-by: Gray Mackall &lt;mackall@google.com&gt;
diff --git a/docs/platforms/android/Android-Platform-Views.md b/docs/platforms/android/Android-Platform-Views.md
@@ -28,13 +28,49 @@ within their Flutter UI.
 
 # Approaches
 
-There are currently three different implementations of Android platform views:
+There are currently four different implementations of Android platform views:
+- [Hybrid Composition++](#hybrid-composition) (HCPP)
 - [Virtual Display](Virtual-Display.md) (VD)
 - [Hybrid Composition](../Hybrid-Composition.md) (HC)
 - [Texture Layer Hybrid Composition](Texture-Layer-Hybrid-Composition.md) (TLHC)
 
 Each has a different set of limitations and tradeoffs, as discussed below. The pages linked above give details about each implementation.
 
+## Hybrid Composition++
+
+This mode is the latest hybrid composition strategy, and is 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 is enabled via configuration rather than standard Dart initialization methods (`initAndroidView`, etc.).
+
+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 cannot be passed to `flutter build` commands. For release builds, use the manifest configuration below.*
+
+2. **AndroidManifest.xml**:
+   Include a `<meta-data>` tag inside the `<application>` block of your `AndroidManifest.xml`:
+   ```xml
+   <meta-data
+       android:name="io.flutter.embedding.android.EnableHcpp"
+       android:value="true" />
+   ```
+
+### Limitations and Known Issues
+The following is a list of limitations and known issues. If you encounter an issue not listed below, please file an issue!
+- **SurfaceView Compatibility**: Opting in is currently not recommended if your application contains a platform view which is or contains a native [`SurfaceView`](https://developer.android.com/reference/android/view/SurfaceView) (often used by video players or map plugins), due to clipping issues. This is tracked in https://github.com/flutter/flutter/issues/175546.
+- **Complex Overlay Stacking**: Transparent platform views will not display correctly in layout stacks structured as: Flutter canvas -> Platform View -> Overlay -> Transparent Platform View, when all four of these layers intersect.
+
 ## Virtual Display
 
 This mode works by rendering the platform view into [a `VirtualDisplay`](https://developer.android.com/reference/android/hardware/display/VirtualDisplay), whose contents are connected to [a Flutter `Texture`](https://api.flutter.dev/flutter/widgets/Texture-class.html).
@@ -61,6 +97,7 @@ In most cases this combines the best aspects of Virtual Display and Hybrid Compo
 
 This display mode requires SDK 23 or later.
 
+
 # Selecting a mode
 
 Usually Android platform views are created with one of the `init*` methods:
