Right now we do it whenever the platform views preview flag is on.
This is less efficient, filed
https://github.com/flutter/flutter/issues/24133 to only do this when
there's a platform view in the tree.

The `id` parameter of onDispose is passed as the method argument and not as
part of a map.

Moved the frame buffer specific logic from IOSGLContext to IOSGLRenderTarget.

use recording canvases for overlays

Support platform view overlays with gl rendering.

This also changes the overlay canvases (for both software and gl
rendering) be recording canvases, and only rasterize them after
finishing the paint traversal.

Handing a UIView refererence directly to the engine makes it challenging
for plugin authors to retain a controller for that UIView (e.g the
controller that talks over the platform channel) for as long as the
embedded view is needed.

We instead make the factory return a FlutterPlatformView which is a
wrapper around the UIView that the engine retains as long as the
platform view instance is needed. This allows plugin authors to keep
their control logic in the FlutterPlatformView and know that the engine
is responsible for retaining the reference.

* Don't block the platfrorm thread on simulator mDNS publishing

When we visit a PlatformViewLayer during the paint traversal it replaces
the PaintContext's canvas with a new one that is painted ontop of the
embedded view.
We need to make sure that operations applied by parent layers are also
applied to the new canvas.

To achieve this we collect all the canvases in a SkNWayCanvas and use
this canvas by non leaf nodes. Leaf nodes still paint only to the "current"
canvas.

This PR moves the overlay canvas creation from the paint phase to the
preroll phase, collects them into a SkNWayCanvas and set it in
PaintContext.

To keep this PR focused, I only used the internal_nodes_canvas in the
tranform_layer.
Will followup with a PR that changes all internal layers to use the
internal_nodes_canvas.

* fix setInitialRoute

When the flag is true, we currently use a single thread configuration,
and disabled the raster cache for opacity layers.

The flag's name is 'io.flutter_embedded_views_preview'.

The overlay surfaces are going to be the same IOSSurface implementation
with the platform views controller set to null (so these are surfaces
that don't support embedding platform views to them).

  * Adds a FlutterOverlayView which is a UIView that's showing an
    overlay surface.
  * Creates an overlay surface for each embedded UIView (done in
    FlutterPlatformViewsController).
  * Changes CompositeEmbeddedView to return a new canvas.
  * Makes the PlatformViewLayer replace the PaintContext's canvas with
    the canvas for the overlay view.
  * Changed canvas in PaintContext to be a pointer so it can be changed.

TBD in following PRs:
  * Copy the current canvas state when replacing a canvas in PaintContext.
  * Make FlutterOverlayView work with a GL backend (currently it only
    works with software rendering)

Also tracks the order of embedded views from frame to frame, and only
removes and reattaches subviews if there is a structural change to the
UIView hierarchy.

This PR breaks PlatformViewsController's construction dependency on FlutterView,
which allows making FlutterEngine its owner instead of
FlutterViewController.

Also renamed the FlutterScreenshotDelegate to FlutterViewEngineDelegate
which is FlutterView's delegate to the engine, and expanded it to
provide a view embedder.

This allows the framework to decide whether and when a touch event
sequence arrives to the embedded view. Which gives the framework the
ability to manage hit testing and gesture disambiguation for embedded
UIViews.

We achieve this by wrapping each embedded UIView with another UIView that has
a custom UIGestureRecognizer that delays touch events from being
delivered, and another UIGestureRecognizer that makes sure to let
Flutter know of events that are hit tested to the embedded view.

* Ensure Simulator publishes mDNS records on loopback interface.

* Update FlutterPlugin.h docs, suppress warning for older API

For flow to manipulate the embedded UIViews during the paint traversal
it needs some hook in PaintContext.
This PR introduces a ViewEmbeder interface that is implemented by the
iOS PlatformViewsController and plumbs it into PaintContext.

The ViewEmbedder interface is mainly a place holder at this point, as
this PR is focused on just the plumbing.

* Create FlutterEngine to manage a Shell to support maintaining execution state across instances of FlutterViewControllers
* Refactor PlatformViewIOS to support adding or removing a FlutterViewController dynamically
* Refactor FlutterDartHeadlessCodeRunner to implement FlutterEngine
* Refactor FlutterViewController to accept a FlutterEngine at initialization or to create one for backwards compatibility; any Shell related responsibilities are now passed through to the Engine instance
* Remove FlutterNavigationController (unused)
* Update all public Objective C doc comments to be consistent and formatable
* Add public documentation to all public headers

Adds a FlutterPlatformViewFactory protocol - a simple factory protocol to be implemented by plugins
  that exposes a UIView for embedding in Flutter apps.
* Adds a FlutterPlatformView protocol, which is used to associate a
  dispose callback with a `UIView` created by a FlutterPlatformViewFactory.
* Exposes a registerViewFactory method in FlutterPluginRegistrar.
* Implements the `flutter/platform_views` system channel on iOS, allowing
  Dart code to ask for creation/destruction of UIViews.

* Allow FlutterViewController to specify whether its FlutterView is opaque

According to the iOS docs, implementing
`- (id)insertDictationResultPlaceholder`

```Implementation of this method is optional but can be done when you want to provide a specific rectangle for the placeholder animation while the dictation results are being processed. ```

If you do not implement this method, UIKit will insert a default placeholder of 10 whitespace characters. By overriding this, no placeholder text will be inserted. If you implement the `insertDictationResultPlaceholder`, you must implement
`- (void)removeDictationResultPlaceholder:(id)placeholder willInsertResult:(BOOL)willInsertResult`

* Locale Passing

* Pass full locale list and script and variant codes to framework

* Working Android locale list passing and fallback

* Publish port of observatory over mDNS

Add a `-[FlutterViewController setFlutterViewDidRenderCallback:]`
method on iOS so client applications can be notified when the Flutter
view has rendered.  This can be used for add2app cases to determine
when to take an initial screenshot for comparisons in automated
tests.

The callback is expected to be an Objective-C block (or Swift
closure).  I chose to support only a single callback because it's
much simpler (especially since it does not require a separate method
to unregister the callback), and it's not clear that there are use
cases that would justify additional complexity.  Clients have the
flexibility to make their callback invoke other callbacks anyway.

I alternatively considered adding a `-[FlutterViewController
viewDidRenderFirstFlutterFrame]` method that clients could override
in a subclass, but using an Objective-C block seems more flexible and
less of a burden.

Fixes https://github.com/flutter/flutter/issues/20665

* Missing dealloc method in FlutterEventChannel

Remove touch mapper and respect the UITouch phase when calculating the pointer data change type. (#6430)

The touch mapper was a relic of a time when the pointer IDs had to be less
than 16. Not respecting the touch phase is getting in the way of clients that
fake their own touches. Turns out the AppDelegate also like to fake touches to
simulate status bar events. Now, except in cases where there is a specific
override in place, the UI touch phase is respected.

* SystemNavigator.pop can pop w/o UINavigationController

* Fix a compilation problem when  using iPhoneOS12.0sdk(Xcode10).

This will not be active on the Framework until https://github.com/flutter/flutter/pull/22221 lands.

* If isolate is already running, return true

* Use shell::Engine::RunStatus as result of Engine::Run