This is a non-breaking addition to the stable Flutter Embedder API and exposes a
subset of the functionality provided by Dart_PostCObject API in a stable and
tested manner to custom embedder implementations.

Send port acquisition can currently be done as described in the unit-test but
there may be opportunities to extend this API in the future to access ports more
easily or create ports from the native side.

The following capabilities of the the Dart_PostCObject API are explicitly NOT
exposed:
* Object arrays: This allows callers to create complex object graphs but only
  using the primitives specified in the native API. I could find no current use
  case for this and would have made the implementation a lot more complex. This
  is something we can add in the future if necessary however.
* Capabilities and ports: Again no use cases and I honestly I didn’t understand
  how to use capabilities. If needed, these can be added at a later point by
  appending to the union.

Fixes https://github.com/flutter/flutter/issues/46624
Fixes b/145982720

Add a test to verify behavior discussed in b/143612326

This earlier pattern was to use callbacks with latching.

Assert that arc end caps on canvases with root surface transformations are drawn correctly. (#14359)

Verifies that the Skia commit https://skia-review.googlesource.com/c/skia/+/259174 has been pulled into the engine. This should have happened in the roll https://github.com/flutter/engine/pull/14345.

Fixes https://github.com/flutter/flutter/issues/46691
Fixes b/142280381

* Remove erroneous ChildView opacity

* Wire frame metrics through contexts

* Maintain layer stack inside of SceneBuilder

* Remove EnsureSingleChild

* Centralize system-composite and elevation logic

* Wire up OpacityLayer to Scenic

This issue was hidden by an incorrect test expectation that has been corrected.

Fixes b/144555069
Fixes https://github.com/flutter/flutter/issues/45991

This allows custom compositors to affect scene builder modifications made
to the platform view.

Fixes https://github.com/flutter/flutter/issues/44211
Fixes b/143612326

This incorrect assumption led to the introduction of a failure on an external embedder. Also dries up the section that copies the picture to the embedder managed render targets.

Fixes https://github.com/flutter/flutter/issues/43906
Fixes https://b.corp.google.com/issues/143529469

This is a duplicate of flutter/engine#13360 with the test switched to use the software backend instead of the GL backend.

After some debugging and testing on another GL embedder I think the issue with the test is some bug having to do with the GL implementation in the test harness specifically. 

Fixes flutter/flutter#38903

The earlier assumption was that the render target would be re-materialized per frame. The render target needs its own picture recorder to be create per frame as well. When render targets are cached in the registry, an existing target will be reused. But submitting the previous frame would have discarded the recorder already. The layer tree paint would then attempt to dererence a null canvas causing a crash at runtime.

Added tests to ensure that this does not happen both with and without a custom compositor specified by the embedder. I am going to rework this code so that the external view embedders thinks of render target access on a per frame basis but that is a larger change. This smaller patchset should unblock broken builds.

Fixes b/144093523

Ensure that the device pixel ratio is taken into account with window metrics in physical pixels. (#13708)

This was originally patched in https://github.com/flutter/engine/pull/13193 but
the unit-tests were written under the mistaken assumption (that has been
documented already) that the Flutter window metrics used logical pixel
coordinates. That mistake has been corrected and additional tests to verify
rendering intent has been added.

Fixes https://github.com/flutter/flutter/issues/43906
Fixes https://b.corp.google.com/issues/143529469

This caused EmbedderTest.VerifyB143464703 to fail after merging into
master.

```
../../flutter/shell/platform/embedder/tests/embedder_unittests.cc:3111: Failure
Value of: ImageMatchesFixture("verifyb143464703.png", renderered_scene)
  Actual: false
Expected: true
[  FAILED  ] EmbedderTest.VerifyB143464703 (2507 ms)
```

This reverts commit 3ad3bc76.

Previously the cache was disabled on whether or not PlatformViews were
globally enabled. Instead track their existence in the view hierarchy
and only disable RasterCache if a PlatformView is actually present.

This used to only be handled correctly for non-root layer backing stores. This
was mostly a side effect of the fact that we used recording canvases instead of
rendering directly into the backing store. We now use recording canvases
consistently.

Fixes b/143464703
Fixes https://github.com/flutter/flutter/issues/43732

For embedder code that is configured for both AOT and JIT mode Dart execution
based on the Flutter engine being linked to, this runtime check may be used to
appropriately configure the `FlutterProjectArgs`. In JIT mode execution, the
kernel snapshots must be present in the Flutter assets directory specified in
the `FlutterProjectArgs`. For AOT execution, the fields `vm_snapshot_data`,
`vm_snapshot_instructions`, `isolate_snapshot_data` and
`isolate_snapshot_instructions` (along with their size fields) must be specified
in `FlutterProjectArgs`.

This was previously only possible by sending an undocumented payload over an engine managed channel.

This reverts commit 6c2381da and applies iOS fixes.

This reverts commit e53d10c3.

The contents rendered into the backing stores are already correctly scaled.
The initial implementation assumed this also held true for the metrics obtained
via embedded view parameters.

Fixes b/142699417

Embedders may use this to specify a thread whose event loop is managed by them
instead of the engine. In addition, specifying the same task runner for both
the platform and render task runners allows embedders to effectively perform
GPU rendering operations on the platform thread.

To affect this change, the following non breaking changes to the API have been
made:

* The `FlutterCustomTaskRunners` struct now has a new field `render_task_runner`
  for the specification of a custom render task runner.
* The `FlutterTaskRunnerDescription` has a new field `identifier`. Embedders
  must supply a unique identifier for each task runner they specify. In
  addition, when describing multiple task runners that run their tasks on the
  same thread, their identifiers must match.
* The embedder may need to process tasks during `FlutterEngineRun` and
  `FlutterEngineShutdown`. However, the embedder doesn't have the Flutter engine
  handle before `FlutterEngineRun` and is supposed to relinquish handle right
  before `FlutterEngineShutdown`. Since the embedder needs the Flutter engine
  handle to service tasks on other threads while these calls are underway,
  there exist opportunities for deadlock. To work around this scenario, three
  new calls have been added that allow more deliberate management of the Flutter
  engine instance.
  * `FlutterEngineRun` can be replaced with `FlutterEngineInitialize` and
    `FlutterEngineRunInitialized`. The embedder can obtain a handle to the
    engine after the first call but the engine will not post any tasks to custom
    task runners specified by the embedder till the
    `FlutterEngineRunInitialized` call. Embedders can guard the Flutter engine
    handle behind a mutex for safe task runner interop.
  * `FlutterEngineShutdown` can be preceded by the `FlutterEngineDeinitialize`
    call. After this call the Flutter engine will no longer post tasks onto
    embedder managed task runners. It is still embedder responsibility to
    collect the Flutter engine handle via `FlutterEngineShutdown`.
* To maintain backwards compatibility with the old APIs, `FlutterEngineRun` is
  now just a convenience for `FlutterEngineInitialize` and
  `FlutterEngineRunInitilaized`. `FlutterEngineShutdown` now implicitly calls
  `FlutterEngineDeinitialize` as well. This allows existing users who don't care
  are custom task runner interop to keep using the old APIs.
* Adds complete test coverage for both old and new paths.

Fixes https://github.com/flutter/flutter/issues/42460
Prerequisite for https://github.com/flutter/flutter/issues/17579

Add a unit-test to verify that root surface transformation affect platform view coordinates. (#12783)

See b/141980393 for details.

In the issue, the embedder (assumed to render Flutter contents of size 800 x 600 [1]) is meant to be displayed on its side. To achieve this, it specifies a root surface transformation that translates the surface by its width (or height when it held in the correct viewing position) and then rotates it counter-clockwise by 90 degrees. This test verifies that the Flutter Engine accounts for those transformations in the custom compositor platform view coodinates.

[1] The actual size is something different. 800x600 is for illustrative purposes.

Re-enabling this is tracked in https://github.com/flutter/flutter/issues/41999

This reverts commit fcc4ab32.

Fixes https://github.com/flutter/flutter/issues/41394 and other
related correctness issues.

TBR: @arbreng @jason-simmons @mehmetf 

On Fuchsia, add a build flag for compositing OpacityLayers using the system
compositor vs Skia, which exposes a fastpath for opacity via Scenic.
This will only work under certain circumstances, in particular nested
OpacityLayers will not render correctly!

On Fuchsia, add a build flag for compositing PhysicalShapeLayers using
the system compositor vs Skia. Set to off by default, which restores
performant shadows on Fuchsia.

Remove the opacity exposed from ChildView, as that was added mistakenly.

Finally, we centralize the logic for switching between the
system-composited and in-process-composited paths inside of
ContainerLayer. We also centralize the logic for computing elevation
there. This allows the removal of many OS_FUCHSIA-specific code-paths.

Test: Ran workstation on Fuchsia; benchmarked before and after
Bug: 23711
Bug: 24163

* Fix broken tests

* Add windows font change logic

* update

* fix comment

Account for root surface transformation on the surfaces managed by the external view embedder. (#11384)

The earlier design speculated that embedders could affect the same
transformations on the layers post engine compositor presentation but before
final composition.

However, the linked issue points out that this design is not suitable for use
with hardware overlay planes. When rendering to the same, to affect the
transformation before composition, embedders would have to render to an
off-screen render target and then apply the transformation before presentation.
This patch negates the need for that off-screen render pass.

To be clear, the previous architecture is still fully viable. Embedders still
have full control over layer transformations before composition. This is an
optimization for the hardware overlay planes use-case.

Fixes b/139758641

The tests we write must be resilient to the order in which they are run in the
harness. That is, they must not rely on global state set by other tests that
have already run in the process. Also, these tests must themselves be
repeatable. That is, they must correctly clean up after themselves and be able
to run successfully again in the same process.

This patch adds some safeguards against (but does NOT guarantee) the addition of
tests that violate the dictum.

Additionally, test failures must be easily reproducible for folks investigating
the test failure. Also, tests that assert correctness of unrelated code must not
stop progress on the authors patch.

This changes does not hinder reproducibility of test failures because the random
seed is printed in the logs before running each test. Developers attempting to
reproduce the failure locally can do the same via the following invocation
`--gtest_shuffle --gtest_repeat=<the count> --gtest_random_seed=<seed from failing run>`.

This change does introduce potential burden on patch authors that may see
failures in unrelated code as a newly failing shuffle seed is used on their
runs. To ameliorate this, we will formulate guidance for them to aggressively
mark such tests as disabled and file bugs to enable the same.

The test seed is intentionally kept low because it’s purpose is to test that
individual tests are repeatable. It must not be used as a replacement for
fuzzing.

This change sets up a "spying canvas" to try and detect empty canvases.
When using platform views with a custom embedder, if a platform view
overlay canvas is known to be empty we skip creating a compositor layer
for that overlay.

Uses the same technique used during OpenGL composition to elide root surface access. The refactoring of this approach is tracked in https://github.com/flutter/flutter/issues/38466

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

We will end up creating fewer threads in tests.

No functional change. Just makes testing with fixture images easier. Adding a
whole lot more tests that use this path for the embedder surface rotation
patches. Want to land stuff in smaller chunks.

The root canvas is managed by the external view embedder when using a custom
compositor. Due to this, frame submission on the surface will not end up
flushing the same (because the surface doesn’t have it to begin with). Fixed
with tests.

This test queues tasks to a custom task runner that runs the tasks on the
platform thread.  After shutting down the engine, the test must wait until
these tasks are drained before the test exits.

This issue would only manifest when a custom task runner was being used with
a custom compositor. Both were tested separately but not together. A new
test has been added for this. We still create the GPU thread merger
unnecessarily but I can patch that later. I also cleaned up the existing
custom task runner test to not submit tasks on a dead engine as they just
log errors unnecessarily.

Filed new: https://github.com/flutter/flutter/issues/38844

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

This exposes the `Settings::leak_vm` flag to custom embedders. All embedder
unit-tests now shut down the VM on the shutdown of the last engine in the
process. The mechanics of VM shutdown are already tested in the Shell unit-tests
harness in the DartLifecycleUnittests set of of assertions. This just exposes
that functionality to custom embedders. Since it is part of the public stable
API, I also switched the name of the field to be something less snarky than the
field in private shell settings.