[stable] [Flutter GPU] Add a project-level Flutter GPU setting to the Linux and Windows embedders - #190872

Cherry-pick of #190684 (4ff86d444fb94c39c38111f4b9be649bb716dff7) onto flutter-3.47-candidate.0. It applies cleanly with no conflicts.

The 3.47.0 cherry-pick window is already closed, so this is a request to reopen the conversation rather than a routine cherry-pick. The reasoning is under "Why this is requested after the window closed" below, and I am happy to take a no.

Issue Link:

#190871

Why this is requested after the window closed:

This is an API addition rather than a regression fix, so it does not meet the usual bar. Three things make it worth asking about anyway.

Flutter GPU already has a permanent, project-level opt-in on every other platform (FLTEnableFlutterGPU in Info.plist on iOS and macOS, the EnableFlutterGPU manifest key on Android). Linux and Windows are the only platforms with no equivalent, so this closes a parity gap rather than adding new capability.

Release-mode desktop builds compile out GetSwitchesFromEnvironment (engine_switches.cc guards it with #ifndef FLUTTER_RELEASE), so --enable-flutter-gpu reaches the engine only under flutter run. Without a project-level setter there is no way at all to ship a released Linux or Windows app that uses package:flutter_gpu.

It landed on master on August 7, two days after flutter-3.48-candidate.0 branched on August 5, so it missed both this branch and the next beta branch. If it is not picked up here, the first beta carrying it is 3.49 and the first stable is roughly a quarter out.

Impacted Users:

Developers shipping Flutter desktop apps on Linux and Windows that use package:flutter_gpu, either directly or through a package built on top of it. Issue #167734 has been open since April 2025 with users repeatedly asking how to enable Flutter GPU on Windows, and the most recent comment describes exactly this case, that the command line flag works under flutter run but a packaged executable has no way to set it.

Impact Description:

Production apps on Linux and Windows cannot ship Flutter GPU at all. A release build throws on the first Flutter GPU call with "Flutter GPU must be enabled via the Flutter GPU manifest setting", and that message names only the iOS and Android opt-ins because the desktop ones did not exist. This does not affect development, since flutter run --enable-flutter-gpu works, which is what makes it easy to discover the problem only at packaging time.

Changelog Description:

[flutter/190871] Flutter GPU could not be enabled in release builds on Linux and Windows, since those embedders had no project-level opt-in and release builds ignore engine switches from the environment.

Workaround:

No practical one. Shipping the app in debug or profile mode is the only way to get the environment switches honored, and neither is shippable. The alternative is patching the embedder and building a custom engine.

Risk:

What is the risk level of this cherry-pick?

• Low
• Medium
• High

The change is additive and defaults to off. Both embedders append --enable-flutter-gpu only when the project setting is true, and skip it when an environment switch already carries it, so an app that does not opt in produces a byte-identical switch list. Nothing in the engine, Impeller, or the rendering path changes. The Linux side also hoists a repeated GetSwitchesFromEnvironment() call into a local, which is behavior neutral.

One caveat worth naming. A bool enable_flutter_gpu field is appended to FlutterDesktopEngineProperties in the public flutter_windows.h, which changes that struct's layout. The header and flutter_windows.dll ship together in the SDK artifact cache so they stay consistent, but it is a public C struct change, and once it ships in a stable the shape of the API is locked in.

Test Coverage:

Are you confident that your fix is well-tested by automated tests?

• Yes
• No

Unit tests cover both embedders. On Linux, fl_dart_project_test.cc covers the getter, setter, and default, and fl_engine_test.cc covers switch forwarding and the environment switch deduplication. On Windows, dart_project_unittests.cc, flutter_project_bundle_unittests.cc, and flutter_windows_engine_unittests.cc cover the client wrapper, the project bundle, and the engine switch assembly.

Validation Steps:

1. Create a Flutter app that calls into package:flutter_gpu and run it in release mode on Linux or Windows without the new setting. Confirm it throws "Flutter GPU must be enabled via the Flutter GPU manifest setting".
2. On Linux, add fl_dart_project_set_enable_flutter_gpu(project, TRUE); in linux/runner/my_application.cc. On Windows, add project.set_enable_flutter_gpu(true); in windows/runner/main.cpp.
3. Build in release mode and launch the packaged binary directly rather than through flutter run. Confirm Flutter GPU initializes and renders.
4. Confirm an app that does not set the flag behaves exactly as before.
5. Run the Linux and Windows embedder unit tests.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.