Exposes FlutterSurfaceView, and FlutterTextureView to FlutterActivity and FlutterFragment. (flutter#41984, flutter#47557) (flutter#16552)

Author: matthew-carroll

ci/licenses_golden/licenses_flutter

@@ -655,8 +655,10 @@ FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/Flutt
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/FlutterSurfaceView.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/FlutterTextureView.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/FlutterView.java
+FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/RenderMode.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/SplashScreen.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/SplashScreenProvider.java
+FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/android/TransparencyMode.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/FlutterEngineCache.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/FlutterEnginePluginRegistry.java

shell/platform/android/BUILD.gn

@@ -138,8 +138,10 @@ android_java_sources = [
   "io/flutter/embedding/android/FlutterSurfaceView.java",
   "io/flutter/embedding/android/FlutterTextureView.java",
   "io/flutter/embedding/android/FlutterView.java",
+  "io/flutter/embedding/android/RenderMode.java",
   "io/flutter/embedding/android/SplashScreen.java",
   "io/flutter/embedding/android/SplashScreenProvider.java",
+  "io/flutter/embedding/android/TransparencyMode.java",
   "io/flutter/embedding/engine/FlutterEngine.java",
   "io/flutter/embedding/engine/FlutterEngineCache.java",
   "io/flutter/embedding/engine/FlutterEnginePluginRegistry.java",

shell/platform/android/io/flutter/embedding/android/FlutterActivity.java

@@ -782,28 +782,26 @@ private boolean isDebuggable() {
 
   /**
    * {@link FlutterActivityAndFragmentDelegate.Host} method that is used by {@link
-   * FlutterActivityAndFragmentDelegate} to obtain the desired {@link FlutterView.RenderMode} that
-   * should be used when instantiating a {@link FlutterView}.
+   * FlutterActivityAndFragmentDelegate} to obtain the desired {@link RenderMode} that should be
+   * used when instantiating a {@link FlutterView}.
    */
   @NonNull
   @Override
-  public FlutterView.RenderMode getRenderMode() {
-    return getBackgroundMode() == BackgroundMode.opaque
-        ? FlutterView.RenderMode.surface
-        : FlutterView.RenderMode.texture;
+  public RenderMode getRenderMode() {
+    return getBackgroundMode() == BackgroundMode.opaque ? RenderMode.surface : RenderMode.texture;
   }
 
   /**
    * {@link FlutterActivityAndFragmentDelegate.Host} method that is used by {@link
-   * FlutterActivityAndFragmentDelegate} to obtain the desired {@link FlutterView.TransparencyMode}
-   * that should be used when instantiating a {@link FlutterView}.
+   * FlutterActivityAndFragmentDelegate} to obtain the desired {@link TransparencyMode} that should
+   * be used when instantiating a {@link FlutterView}.
    */
   @NonNull
   @Override
-  public FlutterView.TransparencyMode getTransparencyMode() {
+  public TransparencyMode getTransparencyMode() {
     return getBackgroundMode() == BackgroundMode.opaque
-        ? FlutterView.TransparencyMode.opaque
-        : FlutterView.TransparencyMode.transparent;
+        ? TransparencyMode.opaque
+        : TransparencyMode.transparent;
   }
 
   /**
@@ -917,6 +915,16 @@ public boolean shouldAttachEngineToActivity() {
     return true;
   }
 
+  @Override
+  public void onFlutterSurfaceViewCreated(@NonNull FlutterSurfaceView flutterSurfaceView) {
+    // Hook for subclasses.
+  }
+
+  @Override
+  public void onFlutterTextureViewCreated(@NonNull FlutterTextureView flutterTextureView) {
+    // Hook for subclasses.
+  }
+
   @Override
   public void onFlutterUiDisplayed() {
     // Notifies Android that we're fully drawn so that performance metrics can be collected by

shell/platform/android/io/flutter/embedding/android/FlutterActivityAndFragmentDelegate.java

@@ -251,8 +251,28 @@ View onCreateView(
       LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
     Log.v(TAG, "Creating FlutterView.");
     ensureAlive();
-    flutterView =
-        new FlutterView(host.getActivity(), host.getRenderMode(), host.getTransparencyMode());
+
+    if (host.getRenderMode() == RenderMode.surface) {
+      FlutterSurfaceView flutterSurfaceView =
+          new FlutterSurfaceView(
+              host.getActivity(), host.getTransparencyMode() == TransparencyMode.transparent);
+
+      // Allow our host to customize FlutterSurfaceView, if desired.
+      host.onFlutterSurfaceViewCreated(flutterSurfaceView);
+
+      // Create the FlutterView that owns the FlutterSurfaceView.
+      flutterView = new FlutterView(host.getActivity(), flutterSurfaceView);
+    } else {
+      FlutterTextureView flutterTextureView = new FlutterTextureView(host.getActivity());
+
+      // Allow our host to customize FlutterSurfaceView, if desired.
+      host.onFlutterTextureViewCreated(flutterTextureView);
+
+      // Create the FlutterView that owns the FlutterTextureView.
+      flutterView = new FlutterView(host.getActivity(), flutterTextureView);
+    }
+
+    // Add listener to be notified when Flutter renders its first frame.
     flutterView.addOnFirstFrameRenderedListener(flutterUiDisplayListener);
 
     flutterSplashView = new FlutterSplashView(host.getContext());
@@ -702,18 +722,18 @@ private void ensureAlive() {
     String getInitialRoute();
 
     /**
-     * Returns the {@link FlutterView.RenderMode} used by the {@link FlutterView} that displays the
-     * {@link FlutterEngine}'s content.
+     * Returns the {@link RenderMode} used by the {@link FlutterView} that displays the {@link
+     * FlutterEngine}'s content.
      */
     @NonNull
-    FlutterView.RenderMode getRenderMode();
+    RenderMode getRenderMode();
 
     /**
-     * Returns the {@link FlutterView.TransparencyMode} used by the {@link FlutterView} that
-     * displays the {@link FlutterEngine}'s content.
+     * Returns the {@link TransparencyMode} used by the {@link FlutterView} that displays the {@link
+     * FlutterEngine}'s content.
      */
     @NonNull
-    FlutterView.TransparencyMode getTransparencyMode();
+    TransparencyMode getTransparencyMode();
 
     @Nullable
     SplashScreen provideSplashScreen();
@@ -749,6 +769,36 @@ PlatformPlugin providePlatformPlugin(
      */
     boolean shouldAttachEngineToActivity();
 
+    /**
+     * Invoked by this delegate when the {@link FlutterSurfaceView} that renders the Flutter UI is
+     * initially instantiated.
+     *
+     * <p>This method is only invoked if the {@link
+     * io.flutter.embedding.android.FlutterView.RenderMode} is set to {@link
+     * io.flutter.embedding.android.FlutterView.RenderMode#surface}. Otherwise, {@link
+     * #onFlutterTextureViewCreated(FlutterTextureView)} is invoked.
+     *
+     * <p>This method is invoked before the given {@link FlutterSurfaceView} is attached to the
+     * {@code View} hierarchy. Implementers should not attempt to climb the {@code View} hierarchy
+     * or make assumptions about relationships with other {@code View}s.
+     */
+    void onFlutterSurfaceViewCreated(@NonNull FlutterSurfaceView flutterSurfaceView);
+
+    /**
+     * Invoked by this delegate when the {@link FlutterTextureView} that renders the Flutter UI is
+     * initially instantiated.
+     *
+     * <p>This method is only invoked if the {@link
+     * io.flutter.embedding.android.FlutterView.RenderMode} is set to {@link
+     * io.flutter.embedding.android.FlutterView.RenderMode#texture}. Otherwise, {@link
+     * #onFlutterSurfaceViewCreated(FlutterSurfaceView)} is invoked.
+     *
+     * <p>This method is invoked before the given {@link FlutterTextureView} is attached to the
+     * {@code View} hierarchy. Implementers should not attempt to climb the {@code View} hierarchy
+     * or make assumptions about relationships with other {@code View}s.
+     */
+    void onFlutterTextureViewCreated(@NonNull FlutterTextureView flutterTextureView);
+
     /** Invoked by this delegate when its {@link FlutterView} starts painting pixels. */
     void onFlutterUiDisplayed();
 

shell/platform/android/io/flutter/embedding/android/FlutterFragment.java

@@ -68,9 +68,11 @@
  * <p>The following illustrates how to pre-warm and cache a {@link FlutterEngine}:
  *
  * <pre>{@code
- * // Create and pre-warm a FlutterEngine. FlutterEngine flutterEngine = new
- * FlutterEngine(context);
- * flutterEngine.getDartExecutor().executeDartEntrypoint(DartEntrypoint.createDefault());
+ * // Create and pre-warm a FlutterEngine.
+ * FlutterEngine flutterEngine = new FlutterEngine(context);
+ * flutterEngine
+ *   .getDartExecutor()
+ *   .executeDartEntrypoint(DartEntrypoint.createDefault());
  *
  * // Cache the pre-warmed FlutterEngine in the FlutterEngineCache.
  * FlutterEngineCache.getInstance().put("my_engine", flutterEngine);
@@ -91,14 +93,10 @@ public class FlutterFragment extends Fragment implements FlutterActivityAndFragm
   protected static final String ARG_APP_BUNDLE_PATH = "app_bundle_path";
   /** Flutter shell arguments. */
   protected static final String ARG_FLUTTER_INITIALIZATION_ARGS = "initialization_args";
-  /**
-   * {@link FlutterView.RenderMode} to be used for the {@link FlutterView} in this {@code
-   * FlutterFragment}
-   */
+  /** {@link RenderMode} to be used for the {@link FlutterView} in this {@code FlutterFragment} */
   protected static final String ARG_FLUTTERVIEW_RENDER_MODE = "flutterview_render_mode";
   /**
-   * {@link FlutterView.TransparencyMode} to be used for the {@link FlutterView} in this {@code
-   * FlutterFragment}
+   * {@link TransparencyMode} to be used for the {@link FlutterView} in this {@code FlutterFragment}
    */
   protected static final String ARG_FLUTTERVIEW_TRANSPARENCY_MODE = "flutterview_transparency_mode";
   /** See {@link #shouldAttachEngineToActivity()}. */
@@ -185,9 +183,8 @@ public static class NewEngineFragmentBuilder {
     private String initialRoute = "/";
     private String appBundlePath = null;
     private FlutterShellArgs shellArgs = null;
-    private FlutterView.RenderMode renderMode = FlutterView.RenderMode.surface;
-    private FlutterView.TransparencyMode transparencyMode =
-        FlutterView.TransparencyMode.transparent;
+    private RenderMode renderMode = RenderMode.surface;
+    private TransparencyMode transparencyMode = TransparencyMode.transparent;
     private boolean shouldAttachEngineToActivity = true;
 
     /**
@@ -241,27 +238,25 @@ public NewEngineFragmentBuilder flutterShellArgs(@NonNull FlutterShellArgs shell
     }
 
     /**
-     * Render Flutter either as a {@link FlutterView.RenderMode#surface} or a {@link
-     * FlutterView.RenderMode#texture}. You should use {@code surface} unless you have a specific
-     * reason to use {@code texture}. {@code texture} comes with a significant performance impact,
-     * but {@code texture} can be displayed beneath other Android {@code View}s and animated,
-     * whereas {@code surface} cannot.
+     * Render Flutter either as a {@link RenderMode#surface} or a {@link RenderMode#texture}. You
+     * should use {@code surface} unless you have a specific reason to use {@code texture}. {@code
+     * texture} comes with a significant performance impact, but {@code texture} can be displayed
+     * beneath other Android {@code View}s and animated, whereas {@code surface} cannot.
      */
     @NonNull
-    public NewEngineFragmentBuilder renderMode(@NonNull FlutterView.RenderMode renderMode) {
+    public NewEngineFragmentBuilder renderMode(@NonNull RenderMode renderMode) {
       this.renderMode = renderMode;
       return this;
     }
 
     /**
-     * Support a {@link FlutterView.TransparencyMode#transparent} background within {@link
-     * FlutterView}, or force an {@link FlutterView.TransparencyMode#opaque} background.
+     * Support a {@link TransparencyMode#transparent} background within {@link FlutterView}, or
+     * force an {@link TransparencyMode#opaque} background.
      *
-     * <p>See {@link FlutterView.TransparencyMode} for implications of this selection.
+     * <p>See {@link TransparencyMode} for implications of this selection.
      */
     @NonNull
-    public NewEngineFragmentBuilder transparencyMode(
-        @NonNull FlutterView.TransparencyMode transparencyMode) {
+    public NewEngineFragmentBuilder transparencyMode(@NonNull TransparencyMode transparencyMode) {
       this.transparencyMode = transparencyMode;
       return this;
     }
@@ -326,12 +321,10 @@ protected Bundle createArgs() {
       }
       args.putString(
           ARG_FLUTTERVIEW_RENDER_MODE,
-          renderMode != null ? renderMode.name() : FlutterView.RenderMode.surface.name());
+          renderMode != null ? renderMode.name() : RenderMode.surface.name());
       args.putString(
           ARG_FLUTTERVIEW_TRANSPARENCY_MODE,
-          transparencyMode != null
-              ? transparencyMode.name()
-              : FlutterView.TransparencyMode.transparent.name());
+          transparencyMode != null ? transparencyMode.name() : TransparencyMode.transparent.name());
       args.putBoolean(ARG_SHOULD_ATTACH_ENGINE_TO_ACTIVITY, shouldAttachEngineToActivity);
       args.putBoolean(ARG_DESTROY_ENGINE_WITH_FRAGMENT, true);
       return args;
@@ -412,9 +405,8 @@ public static class CachedEngineFragmentBuilder {
     private final Class<? extends FlutterFragment> fragmentClass;
     private final String engineId;
     private boolean destroyEngineWithFragment = false;
-    private FlutterView.RenderMode renderMode = FlutterView.RenderMode.surface;
-    private FlutterView.TransparencyMode transparencyMode =
-        FlutterView.TransparencyMode.transparent;
+    private RenderMode renderMode = RenderMode.surface;
+    private TransparencyMode transparencyMode = TransparencyMode.transparent;
     private boolean shouldAttachEngineToActivity = true;
 
     private CachedEngineFragmentBuilder(@NonNull String engineId) {
@@ -440,27 +432,26 @@ public CachedEngineFragmentBuilder destroyEngineWithFragment(
     }
 
     /**
-     * Render Flutter either as a {@link FlutterView.RenderMode#surface} or a {@link
-     * FlutterView.RenderMode#texture}. You should use {@code surface} unless you have a specific
-     * reason to use {@code texture}. {@code texture} comes with a significant performance impact,
-     * but {@code texture} can be displayed beneath other Android {@code View}s and animated,
-     * whereas {@code surface} cannot.
+     * Render Flutter either as a {@link RenderMode#surface} or a {@link RenderMode#texture}. You
+     * should use {@code surface} unless you have a specific reason to use {@code texture}. {@code
+     * texture} comes with a significant performance impact, but {@code texture} can be displayed
+     * beneath other Android {@code View}s and animated, whereas {@code surface} cannot.
      */
     @NonNull
-    public CachedEngineFragmentBuilder renderMode(@NonNull FlutterView.RenderMode renderMode) {
+    public CachedEngineFragmentBuilder renderMode(@NonNull RenderMode renderMode) {
       this.renderMode = renderMode;
       return this;
     }
 
     /**
-     * Support a {@link FlutterView.TransparencyMode#transparent} background within {@link
-     * FlutterView}, or force an {@link FlutterView.TransparencyMode#opaque} background.
+     * Support a {@link TransparencyMode#transparent} background within {@link FlutterView}, or
+     * force an {@link TransparencyMode#opaque} background.
      *
-     * <p>See {@link FlutterView.TransparencyMode} for implications of this selection.
+     * <p>See {@link TransparencyMode} for implications of this selection.
      */
     @NonNull
     public CachedEngineFragmentBuilder transparencyMode(
-        @NonNull FlutterView.TransparencyMode transparencyMode) {
+        @NonNull TransparencyMode transparencyMode) {
       this.transparencyMode = transparencyMode;
       return this;
     }
@@ -519,12 +510,10 @@ protected Bundle createArgs() {
       args.putBoolean(ARG_DESTROY_ENGINE_WITH_FRAGMENT, destroyEngineWithFragment);
       args.putString(
           ARG_FLUTTERVIEW_RENDER_MODE,
-          renderMode != null ? renderMode.name() : FlutterView.RenderMode.surface.name());
+          renderMode != null ? renderMode.name() : RenderMode.surface.name());
       args.putString(
           ARG_FLUTTERVIEW_TRANSPARENCY_MODE,
-          transparencyMode != null
-              ? transparencyMode.name()
-              : FlutterView.TransparencyMode.transparent.name());
+          transparencyMode != null ? transparencyMode.name() : TransparencyMode.transparent.name());
       args.putBoolean(ARG_SHOULD_ATTACH_ENGINE_TO_ACTIVITY, shouldAttachEngineToActivity);
       return args;
     }
@@ -832,38 +821,36 @@ public String getInitialRoute() {
   }
 
   /**
-   * Returns the desired {@link FlutterView.RenderMode} for the {@link FlutterView} displayed in
-   * this {@code FlutterFragment}.
+   * Returns the desired {@link RenderMode} for the {@link FlutterView} displayed in this {@code
+   * FlutterFragment}.
    *
-   * <p>Defaults to {@link FlutterView.RenderMode#surface}.
+   * <p>Defaults to {@link RenderMode#surface}.
    *
    * <p>Used by this {@code FlutterFragment}'s {@link FlutterActivityAndFragmentDelegate.Host}
    */
   @Override
   @NonNull
-  public FlutterView.RenderMode getRenderMode() {
+  public RenderMode getRenderMode() {
     String renderModeName =
-        getArguments()
-            .getString(ARG_FLUTTERVIEW_RENDER_MODE, FlutterView.RenderMode.surface.name());
-    return FlutterView.RenderMode.valueOf(renderModeName);
+        getArguments().getString(ARG_FLUTTERVIEW_RENDER_MODE, RenderMode.surface.name());
+    return RenderMode.valueOf(renderModeName);
   }
 
   /**
-   * Returns the desired {@link FlutterView.TransparencyMode} for the {@link FlutterView} displayed
-   * in this {@code FlutterFragment}.
+   * Returns the desired {@link TransparencyMode} for the {@link FlutterView} displayed in this
+   * {@code FlutterFragment}.
    *
-   * <p>Defaults to {@link FlutterView.TransparencyMode#transparent}.
+   * <p>Defaults to {@link TransparencyMode#transparent}.
    *
    * <p>Used by this {@code FlutterFragment}'s {@link FlutterActivityAndFragmentDelegate.Host}
    */
   @Override
   @NonNull
-  public FlutterView.TransparencyMode getTransparencyMode() {
+  public TransparencyMode getTransparencyMode() {
     String transparencyModeName =
         getArguments()
-            .getString(
-                ARG_FLUTTERVIEW_TRANSPARENCY_MODE, FlutterView.TransparencyMode.transparent.name());
-    return FlutterView.TransparencyMode.valueOf(transparencyModeName);
+            .getString(ARG_FLUTTERVIEW_TRANSPARENCY_MODE, TransparencyMode.transparent.name());
+    return TransparencyMode.valueOf(transparencyModeName);
   }
 
   @Override
@@ -983,6 +970,16 @@ public boolean shouldAttachEngineToActivity() {
     return getArguments().getBoolean(ARG_SHOULD_ATTACH_ENGINE_TO_ACTIVITY);
   }
 
+  @Override
+  public void onFlutterSurfaceViewCreated(@NonNull FlutterSurfaceView flutterSurfaceView) {
+    // Hook for subclasses.
+  }
+
+  @Override
+  public void onFlutterTextureViewCreated(@NonNull FlutterTextureView flutterTextureView) {
+    // Hook for subclasses.
+  }
+
   /**
    * Invoked after the {@link FlutterView} within this {@code FlutterFragment} starts rendering
    * pixels to the screen.