This re-lands #20496 and #21780 after fixing the semantics-enabling code that was causing the post-submit web_smoke_test to fail.
Below is the description from the original PR:
This is a PR for converting the dart:ui code in the engine to use a multi-window API. The goal here is to convert from the window singleton to an API that has the concept of multiple windows. Also, I'm matching up the new PlatformDispatcher class to talk directly to the PlatformConfiguration class in the engine. I'm not attempting to actually enable creating multiple windows here, just migrate to an API that has a concept of multiple windows. The multi-window API in this PR currently only ever creates one window.
The design doc for this change is here.
The major changes in this PR:
Move the platfom-specific attributes out of Window, and into the new PlatformDispatcher class that holds all of the platform state, so that the platform code need only update the configuration on this class.
Create FlutterView, FlutterWindow, and SingletonFlutterWindow classes to separate out the concepts of a view (of which there may be multiple in a window), a window (of which there may be multiple on a screen, and they host views), and a window where there is only ever expected to be one (this hosts the entire API of the former Window class, and will eventually be the type of the window singleton).
Next step after this PR lands:
Remove the Window class entirely (it is replaced by SingletonFlutterWindow). Some minor changes in the Framework are needed to switch to using SingletonFlutterWindow directly first.
The Window class still exists in this PR, but will be removed as soon as the framework is converted to point to the SingletonFlutterWindow class instead. They share the same API, just have different names (Window is currently a subclass of SingletonFlutterWindow). The intention is that the Window name will be freed up to use as a widget class name in the framework for managing windows. The singleton called window will remain, and keep the same API it has now.
Embedders that have access to the Dart native API (only Fuchsia now) may perform
library setup in the isolate create callback. The engine used to depend on the
fact the root isolate entrypoint is invoked in the next iteration of message
loop (via the `_startIsolate` trampoline in `isolate_patch.dart`) to ensure that
library setup occur before the main entrypoint was invoked. However, due to
differences in the way in which message loops are setup in Fuchsia, this
entrypoint was run before the callback could be executed. Dart code on Fuchsia
also has the ability to access the underlying event loops directly. This patch
moves the invocation of the create callback to before user dart code has a
chance to run. This difference in behavior on Fuchsia became an issue when the
isolate initialization was reworked in https://github.com/flutter/engine/pull/21820
for null-safety.
Another issue was discovered in that the callback was being invoked twice, I
fixed that too and added a test.
Fixes https://github.com/flutter/flutter/issues/68732
This removes most of the remaining FLUTTER_NOLINT comments and opts
these files back into linter enforcement.
I've filed https://github.com/flutter/flutter/issues/68273 to require
that all FLUTTER_NOLINT comments be followed by a GitHub issue URL
describing the problem to be fixed.
* Revert "Fix documentation build for window changes. (#21780)"
This reverts commit 931a04683d6eb49fc92059b2384ac5b1618d5422.
* Revert "Migration to PlatformDispatcher and multi-window (#20496)"
This reverts commit 85b0031f73544e448354047dc6a236c0b0808252.
This is a PR for converting the dart:ui code in the engine to use a multi-window API. The goal here is to convert from the window singleton to an API that has the concept of multiple windows. Also, I'm matching up the new PlatformDispatcher class to talk directly to the PlatformConfiguration class in the engine. I'm not attempting to actually enable creating multiple windows here, just migrate to an API that has a concept of multiple windows. The multi-window API in this PR currently only ever creates one window.
The design doc for this change is here.
The major changes in this PR:
Move the platfom-specific attributes out of Window, and into the new PlatformDispatcher class that holds all of the platform state, so that the platform code need only update the configuration on this class.
Create FlutterView, FlutterWindow, and SingletonFlutterWindow classes to separate out the concepts of a view (of which there may be multiple in a window), a window (of which there may be multiple on a screen, and they host views), and a window where there is only ever expected to be one (this hosts the entire API of the former Window class, and will eventually be the type of the window singleton).
Next step after this PR lands:
Remove the Window class entirely (it is replaced by SingletonFlutterWindow). Some minor changes in the Framework are needed to switch to using SingletonFlutterWindow directly first.
The Window class still exists in this PR, but will be removed as soon as the framework is converted to point to the SingletonFlutterWindow class instead. They share the same API, just have different names (Window is currently a subclass of SingletonFlutterWindow). The intention is that the Window name will be freed up to use as a widget class name in the framework for managing windows. The singleton called window will remain, and keep the same API it has now.
Skia is removing the deprecated legacy display setting globals and
associated kLegacyFontHost_InitType. This change replaces all such uses
with default surface properties with no special flags and an unknown
pixel geometry. Flutter never set the associated globals, leaving them
with their initial default values, which were no special flags and
horizontal RGB pixel geometry. The values used here are different but
this change should make no difference as Flutter never mentions
SkFont::kSubpixelAntiAlias to take advantage of the pixel geometry.
Embedders can now notify shell during startup about the various displays and their corresponding settings.
Adds a notion of Display update type which can later include chages to displays during runtime such as addition / removal / reconfiguration of displays.
We also remove the responsibility of providing the refresh rate from `vsync_waiter` to `DisplayManager`.
Rewires existing platform implementations of the said API to use `Shell::OnDisplayUpdate` to notify the display manager of the startup configuration.
DisplayManager is also thread-safe to account for rasterizer and UI thread accesses.
Cleans up header order/grouping for consistency: associated header, C/C++ system/standard library headers, library headers, platform-specific #includes.
Adds <cstring> where strlen, memcpy are being used: there are a bunch of places we use them transitively.
Applies linter-required cleanups. Disables linter on one file due to included RapidJson header. See https://github.com/flutter/flutter/issues/65676
This patch does not cover flutter/shell/platform/darwin. There's a separate, slightly more intensive cleanup for those in progress.
This is part of a larger effort to expose the difference between GrDirectContext,
which runs on the GPU thread and can directly perform operations like uploading
textures, and GrRecordingContext, which can only queue up work to be delivered
to the GrDirectContext later.
This change makes it so that we track all the motion events encountered by `FlutterView` and all of its subviews in the `MotionEventTracker` class, indexed by a unique `MotionEventId`. This identifier is then passed to the Flutter framework as seen in https://github.com/flutter/flutter/pull/60930. Once the gestures take part in gesture disambiguation and are sent back to the engine, we look-up the original motion event using the `MotionEventId` and dispatch it to the platform.
Bug: https://github.com/flutter/flutter/issues/58837
The embedder.h API layer is an implementation detail of the desktop
embeddings, not part of the public API surface, so should not be part of
the public symbol list for those libraries.
Added a new `FlutterEngineAOTData` argument to `FlutterProjectArgs`. Embedders can instantiate and destroy this object via the new `FlutterEngineCreateAOTData` and `FlutterEngineCollectAOTData` methods provided.
If an embedder provides more than one source of AOT data to `FlutterEngineInitialize` or `FlutterEngineRun` (e.g. snapshots as well as `FlutterEngineAOTData`), the engine will error out.
Resolves: https://github.com/flutter/flutter/issues/50778
`FlutterEnginePostCallbackOnAllNativeThreads` schedule a callback to be run on
all engine managed threads. The engine will attempt to service this callback the
next time the message loops for each managed thread is idle. Since the engine
manages the entire lifecycle of multiple threads, there is no opportunity for
the embedders to finely tune the priorities of threads directly, or, perform
other thread specific configuration (for example, setting thread names for
tracing). This callback gives embedders a chance to affect such tuning.
Fixesflutter/flutter#49551
Fixes b/143774406
Fixes b/148278215
Fixes b/148278931
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
This exposes platform_view_id on the embedder API's FlutterSemanticNode.
In bd0f9085e5bdbac74cc6e611f758768f15ad5415 (#8055), platformViewId was
added to SemanticsNode. This field is non-zero when the SemanticsNode
represents a platform view and is typically used by embedders as a means
of identifying locations where a platform view's 'native' accessibility
tree should be injected into the platform-specific accessibility tree
constructed by the embedder.
Due to the intended use of this field, the Flutter framework is meant to
enforce that this node has a child count of zero.
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`.
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
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
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
Fixesflutter/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.
