Adds macro for fragment shaders to support flutter <= 3.44 by gaaclarke · Pull Request #187316 · flutter/flutter

gaaclarke · 2026-05-29T19:02:15Z

#186556 was a breaking change that removed the necessity of flipping y coordinates when sampling in opengles. This was a good improvement but it left fragment shader api users in a prediciment where they had to bump their required flutter SDK. This was particularly unfortunate timing for the framework team's releases. This new temporary macro allows people to author shaders that support flutter 3.44.0 and above.

before

void main() {
  vec2 uv = FlutterFragCoord().xy / u_size;
#ifdef IMPELLER_TARGET_OPENGLES
  uv.y = 1.0 - uv.y;
#endif
  fragColor = texture(u_texture, uv);
}

after (support > 3.44.0)

void main() {
  vec2 uv = FlutterFragCoord().xy / u_size;
  fragColor = texture(u_texture, uv);
}

after (support >= 3.44.0)

void main() {
  vec2 uv = FlutterFragCoord().xy / u_size;
#if defined(IMPELLER_TARGET_OPENGLES) && !defined(IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED)
  uv.y = 1.0 - uv.y;
#endif
  fragColor = texture(u_texture, uv);
}

Pre-launch Checklist

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

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

gemini-code-assist

Code Review

This pull request adds a temporary macro IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED to the Impeller compiler for OpenGLES targets, along with associated unit tests and a test shader fixture. The reviewer suggests renaming this macro to IMPELLER_OPENGLES_FLIP_DEPRECATED across the compiler, tests, and shader fixture to improve readability, as the coordinate flipping behavior is what has been deprecated.

gemini-code-assist · 2026-05-29T19:08:50Z

+        // A temporary macro that allows fragment shader authors to target
+        // Flutter <= 3.44 before the OpenGLES flip was removed.
+        spirv_options.macro_definitions.push_back(
+            "IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED");


The macro name IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED can be confusing because 'unflipped' is the new, correct behavior (which is not deprecated), whereas the 'flip' behavior is what has been deprecated/removed. Naming the macro IMPELLER_OPENGLES_FLIP_DEPRECATED makes the intent much clearer when used in shaders:

#if defined(IMPELLER_TARGET_OPENGLES) && !defined(IMPELLER_OPENGLES_FLIP_DEPRECATED) // Flip y coordinate for older Flutter versions uv.y = 1.0 - uv.y; #endif

This reads naturally as 'if targeting OpenGLES and GLES flipping is not yet deprecated, perform the flip'.

Suggested change

// A temporary macro that allows fragment shader authors to target

// Flutter <= 3.44 before the OpenGLES flip was removed.

spirv_options.macro_definitions.push_back(

"IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED");

// A temporary macro that allows fragment shader authors to target

// Flutter <= 3.44 before the OpenGLES flip was removed.

spirv_options.macro_definitions.push_back(

"IMPELLER_OPENGLES_FLIP_DEPRECATED");

References

Optimize for readability: Code is read more often than it is written. ^(link)

Naming this is a challenge. How about something like IMPELLER_OPENGLES_UNFLIPPED_Y_AXIS?

If IMPELLER_OPENGLES_UNFLIPPED_Y_AXIS is defined, then the Y axis is not flipped. So the block would look like:

#if defined(IMPELLER_TARGET_OPENGLES) && !defined(IMPELLER_OPENGLES_UNFLIPPED_Y_AXIS) uv.y = 1.0 - out_v_norm; #else uv.y = out_v_norm; #endif

indicating that the flip is done if GLES is in use but UNFLIPPED_Y_AXIS is not.

I'm wary of putting DEPRECATED in the macro's name given that the macro is defined when using the new behavior that we intend to adopt permanently. It's unclear if there will ever be a point when we can stop defining the macro.

I'm wary of putting DEPRECATED in the macro's name given that the macro is defined when using the new behavior that we intend to adopt permanently

I think the intention is to warn people not to use it, but instead just migrate their frag code directly.

Yes, I want DEPRECATED in there because the intention is to remove it. When we remove it we can modify the compiler to make its usage an error.

gemini-code-assist · 2026-05-29T19:08:51Z

+  // Test that IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED is defined on
+  // TargetPlatform::kRuntimeStageGLES.
+  {
+    options.target_platform = TargetPlatform::kRuntimeStageGLES;
+    reflector_options.target_platform = TargetPlatform::kRuntimeStageGLES;
+    Compiler compiler = Compiler(fixture, options, reflector_options);
+    // Should fail as the shader has a compilation error in it.
+    EXPECT_EQ(compiler.GetSPIRVAssembly(), nullptr);
+  }
+
+  // Test that IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED is defined on
+  // TargetPlatform::kRuntimeStageGLES3.
+  {
+    options.target_platform = TargetPlatform::kRuntimeStageGLES3;
+    reflector_options.target_platform = TargetPlatform::kRuntimeStageGLES3;
+    Compiler compiler = Compiler(fixture, options, reflector_options);
+    // Should fail as the shader has a compilation error in it.
+    EXPECT_EQ(compiler.GetSPIRVAssembly(), nullptr);
+  }


Update the test case to use the clearer macro name IMPELLER_OPENGLES_FLIP_DEPRECATED to match the compiler implementation.

Suggested change

// Test that IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED is defined on

// TargetPlatform::kRuntimeStageGLES.

{

options.target_platform = TargetPlatform::kRuntimeStageGLES;

reflector_options.target_platform = TargetPlatform::kRuntimeStageGLES;

Compiler compiler = Compiler(fixture, options, reflector_options);

// Should fail as the shader has a compilation error in it.

EXPECT_EQ(compiler.GetSPIRVAssembly(), nullptr);

}

// Test that IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED is defined on

// TargetPlatform::kRuntimeStageGLES3.

{

options.target_platform = TargetPlatform::kRuntimeStageGLES3;

reflector_options.target_platform = TargetPlatform::kRuntimeStageGLES3;

Compiler compiler = Compiler(fixture, options, reflector_options);

// Should fail as the shader has a compilation error in it.

EXPECT_EQ(compiler.GetSPIRVAssembly(), nullptr);

}

// Test that IMPELLER_OPENGLES_FLIP_DEPRECATED is defined on

// TargetPlatform::kRuntimeStageGLES.

{

options.target_platform = TargetPlatform::kRuntimeStageGLES;

reflector_options.target_platform = TargetPlatform::kRuntimeStageGLES;

Compiler compiler = Compiler(fixture, options, reflector_options);

// Should fail as the shader has a compilation error in it.

EXPECT_EQ(compiler.GetSPIRVAssembly(), nullptr);

}

// Test that IMPELLER_OPENGLES_FLIP_DEPRECATED is defined on

// TargetPlatform::kRuntimeStageGLES3.

{

options.target_platform = TargetPlatform::kRuntimeStageGLES3;

reflector_options.target_platform = TargetPlatform::kRuntimeStageGLES3;

Compiler compiler = Compiler(fixture, options, reflector_options);

// Should fail as the shader has a compilation error in it.

EXPECT_EQ(compiler.GetSPIRVAssembly(), nullptr);

}

gemini-code-assist · 2026-05-29T19:08:51Z

+#ifdef IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED
+  fail
+#else


Update the test shader to use the clearer macro name IMPELLER_OPENGLES_FLIP_DEPRECATED to match the compiler implementation.

#ifdef IMPELLER_OPENGLES_FLIP_DEPRECATED fail #else

chunhtai · 2026-05-29T20:42:07Z

              TargetPlatform::kRuntimeStageGLES3) {
        spirv_options.macro_definitions.push_back("IMPELLER_TARGET_OPENGLES");
+        // A temporary macro that allows fragment shader authors to target
+        // Flutter <= 3.44 before the OpenGLES flip was removed.


Once people are onboard, we should have a todo with a linked issue to remove it

bdero

Yeah makes sense.

This issue impacts FragmentProgram shaders which sample from a backdrop texture specifically (ImageFilters). Will document this migration option for the breaking change comms in flutter/website#13419 once it lands. 👍

bdero · 2026-05-29T21:39:37Z

Will document this migration option for the breaking change comms in flutter/website#13419 once it lands. 👍

On second thought, maybe we should just use this to bridge the Material widgets and discourage its use elsewhere. We should just tell users to pin the minimum SDK version to the prerelease ID where the y-flip fix was introduced for new releases of packages that involve ImageFilter shaders which employ the y-flip hackery.
Otherwise we're just kicking the can down the road and we'll just break users a second time when we eventually remove this.

gaaclarke · 2026-05-29T21:44:07Z

On second thought, maybe we should just use this to bridge the Material widgets and discourage its use elsewhere. We should just tell users to pin the minimum SDK version to the prerelease ID where the y-flip fix was introduced for new releases of packages that involve ImageFilter shaders which employ the y-flip hackery.
Otherwise we're just kicking the can down the road and we'll just break users a second time when we eventually remove this.

Yea, that's what I was thinking too. I have a draft for the flutter-announce email and I'm thinking I don't mention IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED. Or it's mentioned as a footnote.

gaaclarke · 2026-06-01T19:09:17Z

friendly ping @jason-simmons @justinmc @chunhtai I'd like wider approval before we go down this route.

chunhtai

LGTM, I am onboard with this approach, but we should wait for @justinmc since we need to make sure the material v1.0.0 leverage this flag.

justinmc

LGTM, but to be sure we're on the same page:

The point of the recent changes to this PR that include IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED is to avoid needing to make a change to the material overscroll stretch shader.
I will release material_ui 1.0.0 with SDK dependency >= 3.44.0, and I will not need to release a followup 1.0.1, because there is no change that needs to happen to the shader in the material library.
This PR will be included in all SDK versions that include #186556 (the PR that caused the bug, which is still unpublished).
Therefore, the only SDK versions that will contain the bug will be the SHAs between the landing of #186556 and the landing of this PR. Those SHAs will express the bug whether a user is using flutter/flutter's material or material_ui. They are also in between published versions, so only users on the master channel could ever end up using them.

justinmc · 2026-06-02T16:03:37Z

              TargetPlatform::kRuntimeStageGLES3) {
        spirv_options.macro_definitions.push_back("IMPELLER_TARGET_OPENGLES");
+        // A temporary macro that allows fragment shader authors to target
+        // Flutter <= 3.44 before the OpenGLES flip was removed.


chunhtai · 2026-06-02T16:46:42Z

The point of the recent changes to this PR that include IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED is to avoid needing to make a change to the material overscroll stretch shader.

I think this is incorrect. The shader will need to change logic based on IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED

  #if !defined(IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED) && defined(IMPELLER_TARGET_OPENGLES)
    uv.y = 1.0 - out_v_norm;
  #else
    uv.y = out_v_norm;
  #endif

e.g. https://gist.github.com/chunhtai/24f06316721731cc132a9f0b9256c215

We need to make sure 1.0.0 include this change

gaaclarke · 2026-06-02T16:58:31Z

I pushed an empty commit, ci was in a bad state looking for the CICD label when it was already there

justinmc · 2026-06-02T17:54:54Z

Ok updating my list:

Release material_ui 1.0.0 without using IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED at SDK dependency >= 3.44.0.
Immediately land the IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED fix in the overscroll shader of material_ui and release material_ui 1.0.1 with SDK dependency >= 3.44.x, where x includes both this PR and a future PR that adds IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED to the overscroll shader.
flutter/flutter's material will be broken on the master channel between the landing of the bug PR ([Impeller] Retire Y-coord-scale plumbing by flipping GLES at the vertex stage #186556) and this PR plus the future shader PR.
material_ui will be broken only for users on the same SDK SHAs mentioned above. Users on 3.44.0 will get 1.0.0 and have no bug. Users on 3.44.1 will get 1.0.1 and have no bug.

What is the benefit of the macro that needs to be removed later then? It seems like material_ui is in the same situation as the earlier version of this PR. I guess 3.44.x will theoretically work with material_ui 1.0.0, but that won't happen thanks to Pub's version resolution.

gaaclarke · 2026-06-02T17:58:23Z

@justinmc that's not quite what we had in mind. We want IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED used in material_ui 1.0.0.

What is the benefit of the macro that needs to be removed later then?

It allows material_ui 1.0.0 to support the main channel and flutter >= 3.44.0. There will be no cherry-pick to 3.44.0 for this approach.

auto-submit · 2026-06-02T18:23:11Z

autosubmit label was removed for flutter/flutter/187316, because - The status or check suite Mac mac_unopt has failed. Please fix the issues identified (or deflake) before re-applying this label.

justinmc · 2026-06-02T18:32:19Z

Ok one more try:

For SDKs where the macro IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED doesn't exist, it will still compile even if material uses the macro, it just won't execute it.
Land a new PR in flutter/flutter that adds the macro to material's overscroll stretch shader. Also land that PR in material_ui. The fix PR by @jason-simmons's (Remove the Y coordinate flip workaround in the Material stretch effect shader now that it is no longer required by the Impeller GLES back end #187247) is superseded by this new PR and won't be needed anymore.
Release material_ui 1.0.0 with SDK dep >=3.44.0.
For anyone using an SDK before the bug PR (186556), they will have no bug, whether on flutter/flutter's material or material_ui. This includes 3.44.0.
For anyone using an SDK from the bug PR until the fix PR (187316), they will have the bug whether on flutter/flutter's material or material_ui. This is only possible on the master channel.
For anyone using an SDK after the fix PR, they will not have the bug, whether they use flutter/flutter's material or material_ui. This includes 3.44.x and later.
Some time in the future, when a new stable SDK has been released and material_ui's SDK dependency has been bumped to it, then we can remove IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED.

If this is true then I think this is good enough for users and a revert of #186556 is not necessary.

~~Can someone write a PR to add IMPELLER_OPENGLES_UNFLIPPED_DEPRECATED to the overscroll stretch shader or should I attempt it?~~ Thanks @chunhtai for volunteering!

…11832) Manual roll requested by tarrinneal@google.com flutter/flutter@701665b...2ba5420 2026-06-03 engine-flutter-autoroll@skia.org Roll Packages from 818b310 to b11504f (8 revisions) (flutter/flutter#187511) 2026-06-03 mdebbar@google.com Add new file patterns for team-web labeler (flutter/flutter#187397) 2026-06-03 engine-flutter-autoroll@skia.org Roll Skia from 279b17fe9fc1 to d625048c853a (12 revisions) (flutter/flutter#187483) 2026-06-03 chris@bracken.jp [SwiftPM] Fix prefer_initializing_formals lint (flutter/flutter#187502) 2026-06-03 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from q27k7_um1GvVrySZS... to ap7MhLX4TdpWRrLS_... (flutter/flutter#187478) 2026-06-03 bkonyi@google.com [SwiftPM] Fix concurrent directory/file/symlink creation crashes (flutter/flutter#186953) 2026-06-03 flar@google.com [Impeller] Fix positioning of text shadow masks (flutter/flutter#187460) 2026-06-02 burak.karahan@mail.ru Remove Material imports from painting tests (flutter/flutter#186937) 2026-06-02 awolff@google.com Add android_hardware_smoke_test integration tests (flutter/flutter#187130) 2026-06-02 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#187471) 2026-06-02 pq@users.noreply.github.com [flutter tool] propagate analytics env to sub-tools (flutter/flutter#186780) 2026-06-02 30870216+gaaclarke@users.noreply.github.com Adds macro for fragment shaders to support flutter <= 3.44 (flutter/flutter#187316) 2026-06-02 116356835+AbdeMohlbi@users.noreply.github.com Small clean-up in different java files under `engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/` (flutter/flutter#186631) 2026-06-02 1961493+harryterkelsen@users.noreply.github.com refactor(web): Unify ui.Path code for CanvasKit and Skwasm (flutter/flutter#187331) 2026-06-02 engine-flutter-autoroll@skia.org Roll Packages from f5d50ca to 818b310 (2 revisions) (flutter/flutter#187441) 2026-06-02 faheemabbas766@gmail.com Allow selecting multi-digit device options (flutter/flutter#186184) 2026-06-02 puneetkukreja98@gmail.com Improve error message for type mismatch in Navigator.pop and maybePop. (flutter/flutter#186571) 2026-06-02 sanaullah.383@hotmail.com Remove semantics_tester import from material_button_test.dart (flutter/flutter#184807) 2026-06-02 bkonyi@google.com [flutter_tools] Refactor hostPlatform to use Abi.current() (flutter/flutter#185369) 2026-06-02 mvincentong@gmail.com Clean up avoid_type_to_string suppressions (flutter/flutter#186869) 2026-06-02 202459002+Lukes-Lair@users.noreply.github.com Update Flutter documentation links in flutter_console.bat (flutter/flutter#187354) 2026-06-02 154381524+flutteractionsbot@users.noreply.github.com Revert "[Impeller] Allow attaching specific texture mip levels and slices" (flutter/flutter#187445) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC stuartmorgan@google.com,tarrinneal@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

Adds macro for fragment shaders to support flutter <= 3.44

1da39a3

flutter-dashboard Bot added the CICD Run CI/CD label May 29, 2026

github-actions Bot added engine flutter/engine related. See also e: labels. e: impeller Impeller rendering backend issues and features requests labels May 29, 2026

adds test

6859ec6

github-actions Bot removed the CICD Run CI/CD label May 29, 2026

gaaclarke added the CICD Run CI/CD label May 29, 2026

gaaclarke marked this pull request as ready for review May 29, 2026 19:07

gaaclarke requested review from bdero, chunhtai, jason-simmons and justinmc May 29, 2026 19:07

gemini-code-assist Bot reviewed May 29, 2026

View reviewed changes

chunhtai reviewed May 29, 2026

View reviewed changes

bdero approved these changes May 29, 2026

View reviewed changes

chunhtai approved these changes Jun 1, 2026

View reviewed changes

justinmc approved these changes Jun 2, 2026

View reviewed changes

kick ci

86ef182

github-actions Bot removed the CICD Run CI/CD label Jun 2, 2026

gaaclarke added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels Jun 2, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 2, 2026

gaaclarke added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 2, 2026

auto-submit Bot added this pull request to the merge queue Jun 2, 2026

Merged via the queue into flutter:master with commit 1787981 Jun 3, 2026
212 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 3, 2026

engine-flutter-autoroll mentioned this pull request Jun 3, 2026

Roll Flutter from 701665b97818 to d16942350867 (21 revisions) flutter/packages#11827

Closed

gaaclarke mentioned this pull request Jun 3, 2026

Remove IMPELLER_OPENGLES_FLIP_DEPRECATED #187517

Open

Conversation

gaaclarke commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

before

after (support > 3.44.0)

after (support >= 3.44.0)

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

jason-simmons May 29, 2026

Choose a reason for hiding this comment

Uh oh!

chunhtai May 29, 2026

Choose a reason for hiding this comment

Uh oh!

gaaclarke May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

chunhtai May 29, 2026

Choose a reason for hiding this comment

Uh oh!

justinmc Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bdero left a comment

Choose a reason for hiding this comment

Uh oh!

bdero commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaaclarke commented May 29, 2026

Uh oh!

gaaclarke commented Jun 1, 2026

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

justinmc Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

chunhtai commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaaclarke commented Jun 2, 2026

Uh oh!

justinmc commented Jun 2, 2026

Uh oh!

gaaclarke commented Jun 2, 2026

Uh oh!

auto-submit Bot commented Jun 2, 2026

Uh oh!

justinmc commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gaaclarke commented May 29, 2026 •

edited

Loading

gaaclarke May 29, 2026 •

edited

Loading

bdero commented May 29, 2026 •

edited

Loading

chunhtai commented Jun 2, 2026 •

edited

Loading

justinmc commented Jun 2, 2026 •

edited

Loading