Allow embedder controlled composition of Flutter layers.

This patch allows embedders to split the Flutter layer tree into multiple
chunks. These chunks are meant to be composed one on top of another. This gives
embedders a chance to interleave their own contents between these chunks.

The Flutter embedder API already provides hooks for the specification of
textures for the Flutter engine to compose within its own hierarchy (for camera
feeds, video, etc..). However, not all embedders can render the contents of such
sources into textures the Flutter engine can accept. Moreover, this composition
model may have overheads that are non-trivial for certain use cases. In such
cases, the embedder may choose to specify multiple render target for Flutter to
render into instead of just one.

The use of this API allows embedders to perform composition very similar to the
iOS embedder. This composition model is used on that platform for the embedding
of UIKit view such and web view and map views within the Flutter hierarchy.
However, do note that iOS also has threading configurations that are currently
not available to custom embedders.

The embedder API updates in this patch are ABI stable and existing embedders
will continue to work are normal. For embedders that want to enable this
composition mode, the API is designed to make it easy to opt into the same in an
incremental manner.

Rendering of contents into the “root” rendering surface remains unchanged.
However, now the application can push “platform views” via a scene builder.
These platform views need to handled by a FlutterCompositor specified in a new
field at the end of the FlutterProjectArgs struct.

When a new platform view in introduced within the layer tree, the compositor
will ask the embedder to create a new render target for that platform view.
Render targets can currently be OpenGL framebuffers, OpenGL textures or software
buffers. The type of the render target returned by the embedder must be
compatible with the root render surface. That is, if the root render surface is
an OpenGL framebuffer, the render target for each platform view must either be a
texture or a framebuffer in the same OpenGL context. New render target types as
well as root renderers for newer APIs like Metal & Vulkan can and will be added
in the future. The addition of these APIs will be done in an ABI & API stable
manner.

As Flutter renders frames, it gives the embedder a callback with information
about the position of the various platform views in the effective hierarchy.
The embedder is then meant to put the contents of the render targets that it
setup and had previously given to the engine onto the screen (of course
interleaving the contents of the platform views).

Unit-tests have been added that test not only the structure and properties of
layer hierarchy given to the compositor, but also the contents of the texels
rendered by a test compositor using both the OpenGL and software rendering
backends.

Fixes b/132812775
Fixes flutter/flutter#35410

ci/licenses_golden/licenses_flutter

@@ -521,6 +521,8 @@ FILE: ../../../flutter/shell/gpu/gpu_surface_metal.h
 FILE: ../../../flutter/shell/gpu/gpu_surface_metal.mm
 FILE: ../../../flutter/shell/gpu/gpu_surface_software.cc
 FILE: ../../../flutter/shell/gpu/gpu_surface_software.h
+FILE: ../../../flutter/shell/gpu/gpu_surface_software_delegate.cc
+FILE: ../../../flutter/shell/gpu/gpu_surface_software_delegate.h
 FILE: ../../../flutter/shell/gpu/gpu_surface_vulkan.cc
 FILE: ../../../flutter/shell/gpu/gpu_surface_vulkan.h
 FILE: ../../../flutter/shell/platform/android/AndroidManifest.xml
@@ -810,9 +812,13 @@ FILE: ../../../flutter/shell/platform/embedder/embedder_engine.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_engine.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_external_texture_gl.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_external_texture_gl.h
+FILE: ../../../flutter/shell/platform/embedder/embedder_external_view_embedder.cc
+FILE: ../../../flutter/shell/platform/embedder/embedder_external_view_embedder.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_include.c
 FILE: ../../../flutter/shell/platform/embedder/embedder_platform_message_response.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_platform_message_response.h
+FILE: ../../../flutter/shell/platform/embedder/embedder_render_target.cc
+FILE: ../../../flutter/shell/platform/embedder/embedder_render_target.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_safe_access.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface.h
@@ -824,6 +830,7 @@ FILE: ../../../flutter/shell/platform/embedder/embedder_task_runner.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_task_runner.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_thread_host.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_thread_host.h
+FILE: ../../../flutter/shell/platform/embedder/fixtures/compositor.png
 FILE: ../../../flutter/shell/platform/embedder/fixtures/main.dart
 FILE: ../../../flutter/shell/platform/embedder/platform_view_embedder.cc
 FILE: ../../../flutter/shell/platform/embedder/platform_view_embedder.h

flow/embedded_views.cc

@@ -6,6 +6,10 @@
 
 namespace flutter {
 
+sk_sp<SkSurface> ExternalViewEmbedder::GetRootSurface() {
+  return nullptr;
+}
+
 bool ExternalViewEmbedder::SubmitFrame(GrContext* context) {
   return false;
 };

flow/embedded_views.h

@@ -194,11 +194,15 @@ class ExternalViewEmbedder {
  public:
   ExternalViewEmbedder() = default;
 
+  virtual ~ExternalViewEmbedder() = default;
+
+  virtual sk_sp<SkSurface> GetRootSurface();
+
   // Call this in-lieu of |SubmitFrame| to clear pre-roll state and
   // sets the stage for the next pre-roll.
   virtual void CancelFrame() = 0;
 
-  virtual void BeginFrame(SkISize frame_size) = 0;
+  virtual void BeginFrame(SkISize frame_size, GrContext* context) = 0;
 
   virtual void PrerollCompositeEmbeddedView(
       int view_id,
@@ -220,8 +224,6 @@ class ExternalViewEmbedder {
 
   virtual bool SubmitFrame(GrContext* context);
 
-  virtual ~ExternalViewEmbedder() = default;
-
   FML_DISALLOW_COPY_AND_ASSIGN(ExternalViewEmbedder);
 
 };  // ExternalViewEmbedder

fml/closure.h

@@ -7,10 +7,50 @@
 
 #include <functional>
 
+#include "flutter/fml/macros.h"
+
 namespace fml {
 
 using closure = std::function<void()>;
 
+//------------------------------------------------------------------------------
+/// @brief      Wraps a closure that is invoked in the destructor unless
+///             released by the caller.
+///
+///             This is especially useful in dealing with APIs that return a
+///             resource by accepting ownership of a sub-resource and a closure
+///             that releases that resource. When such APIs are chained, each
+///             link in the chain must check that the next member in the chain
+///             has accepted the resource. If not, it must invoke the closure
+///             eagerly. Not doing this results in a resource leak in the
+///             erroneous case. Using this wrapper, the closure can be released
+///             once the next call in the chain has successfully accepted
+///             ownership of the resource. If not, the closure gets invoked
+///             automatically at the end of the scope. This covers the cases
+///             where there are early returns as well.
+///
+class AutoFireClosure {
+ public:
+  AutoFireClosure(fml::closure closure) : closure_(closure) {}
+
+  ~AutoFireClosure() {
+    if (closure_) {
+      closure_();
+    }
+  }
+
+  fml::closure Release() {
+    fml::closure closure = closure_;
+    closure_ = nullptr;
+    return closure;
+  }
+
+ private:
+  fml::closure closure_;
+
+  FML_DISALLOW_COPY_AND_ASSIGN(AutoFireClosure);
+};
+
 }  // namespace fml
 
 #endif  // FLUTTER_FML_CLOSURE_H_

fml/mapping.cc

@@ -79,6 +79,17 @@ const uint8_t* DataMapping::GetMapping() const {
 
 // NonOwnedMapping
 
+NonOwnedMapping::NonOwnedMapping(const uint8_t* data,
+                                 size_t size,
+                                 ReleaseProc release_proc)
+    : data_(data), size_(size), release_proc_(release_proc) {}
+
+NonOwnedMapping::~NonOwnedMapping() {
+  if (release_proc_) {
+    release_proc_(data_, size_);
+  }
+}
+
 size_t NonOwnedMapping::GetSize() const {
   return size_;
 }

fml/mapping.h

@@ -99,8 +99,12 @@ class DataMapping final : public Mapping {
 
 class NonOwnedMapping final : public Mapping {
  public:
-  NonOwnedMapping(const uint8_t* data, size_t size)
-      : data_(data), size_(size) {}
+  using ReleaseProc = std::function<void(const uint8_t* data, size_t size)>;
+  NonOwnedMapping(const uint8_t* data,
+                  size_t size,
+                  ReleaseProc release_proc = nullptr);
+
+  ~NonOwnedMapping() override;
 
   // |Mapping|
   size_t GetSize() const override;
@@ -111,6 +115,7 @@ class NonOwnedMapping final : public Mapping {
  private:
   const uint8_t* const data_;
   const size_t size_;
+  const ReleaseProc release_proc_;
 
   FML_DISALLOW_COPY_AND_ASSIGN(NonOwnedMapping);
 };

lib/ui/painting/image_decoder_unittests.cc

@@ -19,7 +19,7 @@ class TestIOManager final : public IOManager {
  public:
   TestIOManager(fml::RefPtr<fml::TaskRunner> task_runner,
                 bool has_gpu_context = true)
-      : gl_context_(has_gpu_context ? gl_surface_.CreateContext() : nullptr),
+      : gl_context_(has_gpu_context ? gl_surface_.CreateGrContext() : nullptr),
         weak_gl_context_factory_(
             has_gpu_context ? std::make_unique<fml::WeakPtrFactory<GrContext>>(
                                   gl_context_.get())

shell/common/rasterizer.cc

@@ -223,17 +223,31 @@ RasterStatus Rasterizer::DrawToSurface(flutter::LayerTree& layer_tree) {
   // for instrumentation.
   compositor_context_->ui_time().SetLapTime(layer_tree.build_time());
 
-  auto* canvas = frame->SkiaCanvas();
-
   auto* external_view_embedder = surface_->GetExternalViewEmbedder();
 
+  sk_sp<SkSurface> embedder_root_surface;
+
   if (external_view_embedder != nullptr) {
-    external_view_embedder->BeginFrame(layer_tree.frame_size());
+    external_view_embedder->BeginFrame(layer_tree.frame_size(),
+                                       surface_->GetContext());
+    embedder_root_surface = external_view_embedder->GetRootSurface();
   }
 
+  // If the external view embedder has specified an optional root surface, the
+  // root surface transformation can be affected by the embedder instead of
+  // having to apply it here.
+  SkMatrix root_surface_transformation =
+      embedder_root_surface ? SkMatrix{} : surface_->GetRootTransformation();
+
   auto compositor_frame = compositor_context_->AcquireFrame(
-      surface_->GetContext(), canvas, external_view_embedder,
-      surface_->GetRootTransformation(), true, gpu_thread_merger_);
+      surface_->GetContext(),  // skia GrContext
+      embedder_root_surface ? embedder_root_surface->getCanvas()
+                            : frame->SkiaCanvas(),  // skia canvas
+      external_view_embedder,                       // external view embedder
+      root_surface_transformation,  // root surface transformation
+      true,                         // instrumentation enabled
+      gpu_thread_merger_            // thread merger
+  );
 
   if (compositor_frame) {
     RasterStatus raster_status = compositor_frame->Raster(layer_tree, false);
@@ -244,10 +258,12 @@ RasterStatus Rasterizer::DrawToSurface(flutter::LayerTree& layer_tree) {
     if (external_view_embedder != nullptr) {
       external_view_embedder->SubmitFrame(surface_->GetContext());
     }
+
     FireNextFrameCallbackIfPresent();
 
-    if (surface_->GetContext())
+    if (surface_->GetContext()) {
       surface_->GetContext()->performDeferredCleanup(kSkiaCleanupExpiration);
+    }
 
     return raster_status;
   }

shell/common/shell_test.cc

@@ -248,5 +248,10 @@ GPUSurfaceGLDelegate::GLProcResolver ShellTestPlatformView::GetGLProcResolver()
   };
 }
 
+// |GPUSurfaceGLDelegate|
+ExternalViewEmbedder* ShellTestPlatformView::GetExternalViewEmbedder() {
+  return nullptr;
+}
+
 }  // namespace testing
 }  // namespace flutter

shell/common/shell_test.h

@@ -99,6 +99,9 @@ class ShellTestPlatformView : public PlatformView, public GPUSurfaceGLDelegate {
   // |GPUSurfaceGLDelegate|
   GLProcResolver GetGLProcResolver() const override;
 
+  // |GPUSurfaceGLDelegate|
+  ExternalViewEmbedder* GetExternalViewEmbedder() override;
+
   FML_DISALLOW_COPY_AND_ASSIGN(ShellTestPlatformView);
 };
 

shell/gpu/BUILD.gn

@@ -18,6 +18,8 @@ source_set("gpu_surface_software") {
   sources = [
     "$gpu_dir/gpu_surface_software.cc",
     "$gpu_dir/gpu_surface_software.h",
+    "$gpu_dir/gpu_surface_software_delegate.cc",
+    "$gpu_dir/gpu_surface_software_delegate.h",
   ]
 
   deps = gpu_common_deps

shell/gpu/gpu_surface_gl_delegate.cc

@@ -22,10 +22,6 @@ SkMatrix GPUSurfaceGLDelegate::GLContextSurfaceTransformation() const {
   return matrix;
 }
 
-flutter::ExternalViewEmbedder* GPUSurfaceGLDelegate::GetExternalViewEmbedder() {
-  return nullptr;
-}
-
 GPUSurfaceGLDelegate::GLProcResolver GPUSurfaceGLDelegate::GetGLProcResolver()
     const {
   return nullptr;

shell/gpu/gpu_surface_gl_delegate.h

@@ -44,7 +44,7 @@ class GPUSurfaceGLDelegate {
 
   // Get a reference to the external views embedder. This happens on the same
   // thread that the renderer is operating on.
-  virtual flutter::ExternalViewEmbedder* GetExternalViewEmbedder();
+  virtual ExternalViewEmbedder* GetExternalViewEmbedder() = 0;
 
   sk_sp<const GrGLInterface> GetGLInterface() const;
 

shell/gpu/gpu_surface_software.cc

@@ -9,11 +9,6 @@
 
 namespace flutter {
 
-flutter::ExternalViewEmbedder*
-GPUSurfaceSoftwareDelegate::GetExternalViewEmbedder() {
-  return nullptr;
-}
-
 GPUSurfaceSoftware::GPUSurfaceSoftware(GPUSurfaceSoftwareDelegate* delegate)
     : delegate_(delegate), weak_factory_(this) {}
 

shell/gpu/gpu_surface_software.h

@@ -5,23 +5,13 @@
 #ifndef FLUTTER_SHELL_GPU_GPU_SURFACE_SOFTWARE_H_
 #define FLUTTER_SHELL_GPU_GPU_SURFACE_SOFTWARE_H_
 
-#include "flutter/flow/embedded_views.h"
 #include "flutter/fml/macros.h"
 #include "flutter/fml/memory/weak_ptr.h"
 #include "flutter/shell/common/surface.h"
-#include "third_party/skia/include/core/SkSurface.h"
+#include "flutter/shell/gpu/gpu_surface_software_delegate.h"
 
 namespace flutter {
 
-class GPUSurfaceSoftwareDelegate {
- public:
-  virtual sk_sp<SkSurface> AcquireBackingStore(const SkISize& size) = 0;
-
-  virtual bool PresentBackingStore(sk_sp<SkSurface> backing_store) = 0;
-
-  virtual flutter::ExternalViewEmbedder* GetExternalViewEmbedder();
-};
-
 class GPUSurfaceSoftware : public Surface {
  public:
   GPUSurfaceSoftware(GPUSurfaceSoftwareDelegate* delegate);

shell/gpu/gpu_surface_software_delegate.cc

@@ -0,0 +1,13 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "gpu_surface_software_delegate.h"
+
+namespace flutter {
+
+ExternalViewEmbedder* GPUSurfaceSoftwareDelegate::GetExternalViewEmbedder() {
+  return nullptr;
+}
+
+}  // namespace flutter

shell/gpu/gpu_surface_software_delegate.h

@@ -0,0 +1,65 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_SHELL_GPU_GPU_SURFACE_SOFTWARE_DELEGATE_H_
+#define FLUTTER_SHELL_GPU_GPU_SURFACE_SOFTWARE_DELEGATE_H_
+
+#include "flutter/flow/embedded_views.h"
+#include "flutter/fml/macros.h"
+#include "third_party/skia/include/core/SkSurface.h"
+
+namespace flutter {
+
+//------------------------------------------------------------------------------
+/// @brief      Interface implemented by all platform surfaces that can present
+///             a software backing store to the "screen". The GPU surface
+///             abstraction (which abstracts the client rendering API) uses this
+///             delegation pattern to tell the platform surface (which abstracts
+///             how backing stores fulfilled by the selected client rendering
+///             API end up on the "screen" on a particular platform) when the
+///             rasterizer needs to allocate and present the software backing
+///             store.
+///
+/// @see        |IOSurfaceSoftware|, |AndroidSurfaceSoftware|,
+///             |EmbedderSurfaceSoftware|.
+///
+class GPUSurfaceSoftwareDelegate {
+ public:
+  //----------------------------------------------------------------------------
+  /// @brief      Called when the GPU surface needs a new buffer to render a new
+  ///             frame into.
+  ///
+  /// @param[in]  size  The size of the frame.
+  ///
+  /// @return     A raster surface returned by the platform.
+  ///
+  virtual sk_sp<SkSurface> AcquireBackingStore(const SkISize& size) = 0;
+
+  //----------------------------------------------------------------------------
+  /// @brief      Called by the platform when a frame has been rendered into the
+  ///             backing store and the platform must display it on-screen.
+  ///
+  /// @param[in]  backing_store  The software backing store to present.
+  ///
+  /// @return     Returns if the platform could present the backing store onto
+  ///             the screen.
+  ///
+  virtual bool PresentBackingStore(sk_sp<SkSurface> backing_store) = 0;
+
+  //----------------------------------------------------------------------------
+  /// @brief      Gets the view embedder that controls how the Flutter layer
+  ///             hierarchy split into multiple chunks should be composited back
+  ///             on-screen. This field is optional and the Flutter rasterizer
+  ///             will render into a single on-screen surface if this call
+  ///             returns a null external view embedder.
+  ///
+  /// @return     The external view embedder, or, null if Flutter is rendering
+  ///             into a single on-screen surface.
+  ///
+  virtual ExternalViewEmbedder* GetExternalViewEmbedder() = 0;
+};
+
+}  // namespace flutter
+
+#endif  // FLUTTER_SHELL_GPU_GPU_SURFACE_SOFTWARE_DELEGATE_H_

shell/platform/android/android_surface_gl.cc

@@ -125,4 +125,9 @@ intptr_t AndroidSurfaceGL::GLContextFBO() const {
   return 0;
 }
 
+// |GPUSurfaceGLDelegate|
+ExternalViewEmbedder* AndroidSurfaceGL::GetExternalViewEmbedder() {
+  return nullptr;
+}
+
 }  // namespace flutter