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.
embedder.h is a C API, so has no namespace, and only uses 'Flutter' as a
prefix for most symbol names. This creates potential collisions with
other code; for instance, FlutterEngine is the name of a type in
embedder.h, but also an ObjC class in the iOS Flutter API.
This adds a macro that can be set to prefix symbol names, allowing
clients (notably, the macOS embedding) to adjust the names used by the
embedding API internally without breaking ABI or API compatibility for
the standard engine build.
Currently the macro is only applied to FlutterEngine, since that's the
symbol that is currently at issue, but it can be expanded to other
symbols in the future.
Messages sent to the embedder host may be one-way messages with no response
handler. If the host calls FlutterEngineSendPlatformMessageResponse on a
one-way message, then just delete the message response handle.
Also update the documentation to indicate that
FlutterEngineSendPlatformMessageResponse must be called for all messages.
Previously the docs implied that some FlutterPlatformMessage objects may
have a null response_handle. The embedder will now set a response_handle for
every message (even if the sender does not expect a response).
Corects a bnuch of typeos throughout teh engien codebsae. Also makes
a couple minor Commonwealth -> US spelling adjustments for consistency
with the rest of Flutter's codebase.
Made use of `misspell` tool:
https://github.com/client9/misspell
Rather than hard-coding the type of incoming events to mouse, and
synthesizing a primary button press for kDown/kUp, expose device kind
and buttons in the API.
For backwards compatibility, if the type is not set, the old behavior is
used. If an embedder sets the type to mouse explicitly, however, they
must also set correct button information.
For the touch type, the API abstracts away the framework's internal
expectation that a button is set for touch down/move for simplicity.
Fixesflutter/flutter#32854
Currently, all Flutter threads are managed by the engine itself. This works for
all threads except the platform thread. On this thread, the engine cannot see
the underlying event multiplexing mechanism. Using the new task runner
interfaces, the engine can relinquish the task of setting up the event
multiplexing mechanism and instead have the embedder provide one for it during
setup.
This scheme is only wired up for the platform thread. But, the eventual goal
is to expose this message loop interoperability for all threads.
This will allow us to easily visualize the time the platform informed the engine of a vsync event, its arguments, and when the engine began its UI thread workload using this information.
Verified that the tests fail on issues like https://github.com/flutter/engine/pull/8166. Unfortunately, there is no x-platform way to perform this check but this should gate incorrect traces being added to the engine.
Some embedders may have to wait on fences asynchronously before committing
contents. This allows them to post a task onto the engine managed thread used
for rendering.
Some clients (e.g., embedded devices) prefer generating persistent cache files for the specific device beforehand, and ship them as readonly files in OTA packages.
This updates the FlutterSemanticsAction enumerator identifiers for the
'move cursor forward/back one word' actions (added in
flutter/engine#8033) for consistency with the 'move cusor forward/back
on character' identifiers.
ABI compatibility is unaffected, but this with require the following
change in any embedder making use of these fields:
Rename:
kFlutterSemanticsActionMoveCursorForwardByWordIndex
to:
kFlutterSemanticsActionMoveCursorForwardByWord
Rename:
kFlutterSemanticsActionMoveCursorBackwardByWordIndex
to:
kFlutterSemanticsActionMoveCursorBackwardByWord
The current assumption is that the embedder will wait till the vsync event and
then fire the callback. However, some embedders have that information upfront.
Since the time point has already been specified by the embedder, there is no
reason to burden the embedder with having to setup a wait either.
Adds support for pointer signals, in a way that will support both discrete events (e.g., scroll wheels, flutter/flutter#22762) and continuous gestures (e.g., trackpad scroll, flutter/flutter#21953).
Also exposes these new event options to the embedder. Does not include code to send the
new events from the platform shells.
This brings the Dart and C++ semantics flag enums back in sync.
In #5902, the ability to move the cursor forward and backward one word
were added to dart:ui, and to the Android embedder, but not to the
SemanticsAction enum on the C++ side.
This brings the Dart and C++ semantics flag enums back in sync.
In #5941, implicit scrolling support was added to SemanticsFlag in
dart:ui, and to the Android embedder, but not to the SemanticsFlags enum
on the C++ side.
This also clarifies/corrects the documentation for this value in dart:ui
and in the embedder API.
Some embedders prefer to minimise the number of semantics node/custom
action updates sent back to the host platform -- for example due to
expensive serialisation mechanisms, etc.
This patch provides a 'batch end' signal that provides embedders with an
indication of when a self-consistent set of semantics node or custom action
updates have been sent.
We overload the node/action ID with information that conveys a batch end
by using an ID (-1) that is never allotted to semantics nodes by the
framework.
Flutter's accessibility APIs consist of three main calls from the
embedder to the Dart application:
1. FlutterEngineUpdateSemanticsEnabled: enables/disables semantics support.
2. FlutterEngineUpdateAccessibilityFeatures: sets embedder-specific
accessibility features.
3. FlutterEngineDispatchSemanticsAction: dispatches an action (tap,
long-press, scroll, etc.) to a semantics node.
and two main callbacks triggered by Dart code:
1. FlutterUpdateSemanticsNodeCallback: notifies the embedder of
updates to the properties of a given semantics node.
2. FlutterUpdateSemanticsCustomActionCallback: notifies the embedder
of updates to custom semantics actions registered in Dart code.
In the Flutter framework, when accessibility is first enabled, the
embedder will receive a stream of update callbacks notifying the
embedder of the full semantics tree. On further changes in the Dart
application, only updates will be sent.
Adds 'add', 'remove', and 'hover' to the set of pointer phases that are
available to embedders. This is necessary for them to send hover events
to the engine.
Allows embedders to specify a callback to be invoked in isolate scope
once root isolate has been created and marked runnable.
As an example of where this is useful, embedder unit test fixtures may
want to include Dart functions backed by a native implementation. On
isolate creation, this patch allows the unit test author to call
Dart_SetNativeResolver in root isolate scope.
FlutterResult is also the name of a class in the Objective-C API
surface, which is problematic when building a framework that contains
both (such as a macOS implementation of the Flutter framework).
As of Dart 2, running from Dart source is no longer supported. Dart
code should now be compiled to kernel form and will be loaded by from
kernel.blob in the assets directory. We retain the struct members for ABI
stability. package_path is also not required since kernel blobs are
self-contained.
