[dart:ui] Introduce PlatformDispatcher.implicitView

[loic-sharma]

This introduces PlatformDispatcher.implicitView (see flutter/flutter#120306).

This is a low-level primitive for the framework's bootstrapping. Most code, including the framework after bootstrapping, will use View.of(context) instead of this new API. This new primitive will let us deprecate the window global.

Goals:

1. Enable multi-window. The PlatformDispatcher.implicitView is nullable. If null, the app must create a window to get a view it can draw into.
2. Backwards compatibility. For "single window" apps, PlatformDispatcher.instance.implicitView should behave as similar to window as possible.
   1. The PlatformDispatcher.instance.implicitView.viewId should be 0.
   2. The PlatformDispatcher.instance.implicitView must be available synchronously at root isolate startup. This allows the framework to determine if it can make single window assumptions at startup.
   3. The PlatformDispatcher.instance.implicitView reference must not change after startup: if it is null at startup, it must always be null; if it is non-null at startup, it must always be non-null. If "single window" app enters headless mode, the implicit view must remain non-null.

In the future, the embedder will control whether an implicit view is created: mobile & legacy desktop apps will have an implicit view, multi-window desktop apps won't have an implicit view. This requires updating the engine's embedder API and is out-of-scope for this change. For now, all apps will have an implicit view.

Part of flutter/flutter#120306

Manual test

Manual test plan...

Modify: https://github.com/flutter/flutter/blob/master/examples/layers/raw/hello_world.dart

diff --git a/examples/layers/raw/hello_world.dart b/examples/layers/raw/hello_world.dart
index 20a53b0c7c..0940ebc49f 100644
--- a/examples/layers/raw/hello_world.dart
+++ b/examples/layers/raw/hello_world.dart
@@ -8,8 +8,9 @@
 import 'dart:ui' as ui;

 void beginFrame(Duration timeStamp) {
-  final double devicePixelRatio = ui.window.devicePixelRatio;
-  final ui.Size logicalSize = ui.window.physicalSize / devicePixelRatio;
+  ui.FlutterView? window = ui.PlatformDispatcher.instance.implicitView;
+  final double devicePixelRatio = window!.devicePixelRatio;
+  final ui.Size logicalSize = window!.physicalSize / devicePixelRatio;

   final ui.ParagraphBuilder paragraphBuilder = ui.ParagraphBuilder(
     ui.ParagraphStyle(textDirection: ui.TextDirection.ltr),
@@ -35,7 +36,7 @@ void beginFrame(Duration timeStamp) {
     ..addPicture(ui.Offset.zero, picture)
     ..pop();

-  ui.window.render(sceneBuilder.build());
+  window!.render(sceneBuilder.build());
 }

 // This function is the primary entry point to your application. The engine

✅ Verify that Windows works as expected:

flutter run .\raw\hello_world.dart -d windows --local-engine host_debug_unopt

✅ Verify that Web works as expected:

flutter run .\raw\hello_world.dart --local-engine host_debug_unopt -d chrome

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide and the C++, Objective-C, Java style guides.
• I listed at least one issue that this PR fixes in the description above.
• I added new tests to check the change I am making or feature I am adding, or Hixie said the PR is test-exempt. See testing the engine for instructions on writing and running engine tests.
• I updated/added relevant documentation (doc comments with ///).
• I signed the CLA.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

[ditman]

web_ui bits look good! Thanks!

[goderbauer]

LGTM

[goderbauer]

Should we add some kind of a warning here that applications and packages should not rely on this property being set and instead acquire the view via other means (e.g. View.of(context) is appropriate for most use cases)? This property is basically just interesting for low-level app bootstrapping.

[goderbauer]

(I guess you're sort of hinting at this with the "see also" section)

[loic-sharma]

Could you take another look? I updated this comment to push people towards View.of instead. The new comment is less clear as to when an implicit view is provided by the platform though...

[goderbauer]

I took a stab below at how I would write the documentation for this property. Feel free to copy it as a whole or bits and pieces that you like or ignore it completely.

---

The implicit [FlutterView] provided by the platform, if any.

If the platform provides an implicit view, it can be used to bootstrap the framework. This is common for platforms designed for single-view applications (e.g. on mobile devices with a single display).

Applications and libraries must not rely on this property being set as it may be null depending on the engine's configuration. Instead, consider using [View.of] to lookup the [FlutterView] the current [BuildContext] is drawing into.

While the properties on the referenced [FlutterView] may change, the reference itself is guaranteed to never change over the lifetime of the application: If this property is null at startup, it will remain so throughout the entire lifetime of the application. If it points to a specific [FlutterView], it will continue to point to the same view until the application is shut down (although the engine may replace or remove the underlying backing surface of the view at its discretion).

See also:

• [PlatformDisptacher.views] for a list of all [FlutterView]s provided by the platform.

[loic-sharma]

That's perfect, will update!

[loic-sharma]

Updated! FYI, I added [View.of] to the "See also" section. It's a little repetitive, but I want to nudge folks towards View.of as much as possible :)

[cbracken]

Added just a couple more suggestions above but this is looking pretty great!

[goderbauer]

Wondering if this maybe should just return the implicit view ID (or null) to avoid that we have to hard-code the magic number here and in platform_configuration.cc.

[loic-sharma]

I had this approach originally but I switched to a boolean instead as we don't have any scenarios where the implicit view will have a non-zero ID. I don't feel strongly either ways though, so let me know if you have a preference.

[goderbauer]

No preference, really. It's all private and internal anyways, so easy to change if it has to.

[loic-sharma]

Sounds good. I'll leave this open so others can chime in :)

[yaakovschectman]

LGTM with one question

[yaakovschectman]

Will/should this always return the 0th view even in multi-window cases?

[loic-sharma]

Yup, if there is an implicit view it is guaranteed to have view ID 0. Note that this is a map and not a list. Furthermore, the implicit view & underlying view exist even if the app transitions to headless mode - this matches today's window behavior.

"Modern" desktop apps won't have an implicit view. These are apps that use the new runner templates that don't exist yet. For these future apps, view ID 0 won't have any special meaning.

[cbracken]

Overall looks good - just a few C++ and doc nits.

[goderbauer]

LGTM 🚀

[dkwingsmt]

What does this test do? To ensure that PlatformDispatcher.instance.implicitView isn't null? But this is only because we don't have an option to control it right? Should we add a TODO or at least comment to explain that this test might (should) be broken once we allow non-implicitView?

[loic-sharma]

This is just a fixture to check whether the implicit view is non-null. The real test is EmbedderTest.ImplicitViewNotNull.

But this is only because we don't have an option to control it right?

Yup that's correct.

Should we add a TODO or at least comment to explain that this test might (should) be broken once we allow non-implicitView?

Good idea, added a TODO to EmbedderTest.ImplicitViewNotNull.

[dkwingsmt]

Same.

[loic-sharma]

From my understanding, only desktop platforms will be able to create windows (and therefore views). All other platforms - mobile and web - will have an implicit view instead. In other words, this test will be correct for the foreseeable future.

Side note: in theory we could allow all embedders to opt-out of the implicit view for add-to-app scenarios. We don't have any concrete plans there though... /cc @goderbauer

[dkwingsmt]

All other platforms - mobile and web - will have an implicit view instead. In other words, this test will be correct for the foreseeable future.

I think we'd rather not assume that (and we don't have to, right?). The user might very possibly attach multiple views from the native code, and the framework will handle them. And with that, the user might even choose not to use the implicit view.

[ditman]

All other platforms - mobile and web - will have an implicit view instead.

Web will (possibly) want to render to multiple different target DIVs at some point, so I guess we're going to have multiple "views" too?

[loic-sharma]

All other platforms - mobile and web - will have an implicit view instead.

Web will (possibly) want to render to multiple different target DIVs at some point, so I guess we're going to have multiple "views" too?

To clarify there's two semi-related things here:

1. Multi-view: all platforms, including web, will have multi-view support from the framework side
2. Implicit view: this replaces the window global

Having an implicit view does not block multi-view. It's just the replacement for the window global. For now, we don't have plans to move web off the implicit view as that's not required for supporting multi-window on desktop.

[ditman]

Thanks for the clarification @loic-sharma (expect a quick call from me soon-ish though, I want to start redoing stuff in the web engine so the multi-view lands more easily!)

[dkwingsmt]

LGTM, nice work!