Fix PlatformView scaling in showCupertinoSheet transitions by laishere · Pull Request #182935 · flutter/flutter

laishere · 2026-02-26T10:34:08Z

The scale transition in showCupertinoSheet for the underlying route defaulted to FilterQuality.medium, which pushes an implicit ImageFilterLayer.

Platform views cannot be correctly sampled or transformed by rasterization-based filters. Consequently, they fail to reflect the scale transformation during the transition animation when an ImageFilterLayer is present, leading to a broken visual effect where the background scales but the platform view remains at its original size.

Solution:

Add a enableFilter parameter to showCupertinoSheet and related classes. When set to false, the transition uses a standard TransformLayer, which allows platform views to scale correctly.
Add a debug-time assertion in PlatformViewLayer.redepthChildren to detect when a platform view is nested inside unsupported filter layers (ImageFilterLayer, ColorFilterLayer, or ShaderMaskLayer). This will help developers catch similar rasterization conflicts earlier.

Fixes: #169495

Example usage

  showCupertinoSheet(
    context: context,
    enableFilter: false, // disable image filter
    scrollableBuilder: (context, _) => PlatformViewWidget(),
  );

Visual Changes

Before vs. After Comparison

Before (Scaling Issue)	After (Correct Scaling)

Notes on Visuals:

Before: Notice how the WebView stays at its original size while the rest of the underlying route scales down.
After: The WebView scales smoothly in sync with the transition when enableFilter is set to false.

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], 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.

gemini-code-assist

Code Review

This pull request addresses a scaling issue with PlatformViews during showCupertinoSheet transitions. It introduces a filterQuality parameter to showCupertinoSheet and related classes, allowing developers to disable the default ImageFilterLayer that causes rendering conflicts with PlatformViews by setting filterQuality to null. The changes plumb this new parameter through CupertinoSheetRoute and CupertinoSheetTransition. Additionally, a debug-time assertion is added to PlatformViewLayer to detect and report when a PlatformView is incorrectly nested within filter-based layers like ImageFilterLayer, ColorFilterLayer, or ShaderMaskLayer, improving developer experience by providing clear error messages for such conflicts. A minor related change adjusts the timing of when debugCreator is set on layers within RenderTransform to ensure this information is available for the new assertion. Finally, tests are added to verify the new assertion logic.

laishere · 2026-02-26T17:46:29Z

Refactored the original implementation: changing the new parameter from filterQuality to enableFilter for simplicity. Defaulting to true which sets the filterQuality to FilterQuality.medium as the original way.

dkwingsmt

Thank you very much for the investigation. Fantastic implementation of the assertion!

My only concern is the API design. I think the current property name is not intuitive enough, especially for those who wonder why their app crashes. I've evaluated several options, and I'm proposing the name hasPlatformViews, which is as explicit as possible on what this property is used for and focuses on the perspective of the developers ("if you have platform views, turn on this to avoid errors" without having to understand why). What do you think?

Also I propose the following doc to acommpany the name:

  /// Whether the underlying route contains platform views.
  ///
  /// Defaults to false, which uses an [ImageFilterLayer] for high-quality scaling.
  /// However, since image filters cannot be applied to platform views, they may 
  /// appear "detached" or remain at their original size while the background 
  /// page scales.
  ///
  /// When set to true, the transition uses a [TransformLayer] instead. This 
  /// ensures platform views scale in sync with the rest of the route, although 
  /// the scaling quality may be slightly lower (less antialiasing).

laishere · 2026-03-31T07:51:31Z

@dkwingsmt Thanks for reviewing. I think hasPlatformViews is a good idea. Do you think we should replace all enableFilter with this or just the public API?

…ition

dkwingsmt

LGTM. Thank you for the investigation!

auto-submit · 2026-04-08T06:59:26Z

autosubmit label was removed for flutter/flutter/182935, because This PR has not met approval requirements for merging. The PR author is not a member of flutter-hackers and needs 1 more review(s) in order to merge this PR.

Merge guidelines: A PR needs at least one approved review if the author is already part of flutter-hackers or two member reviews if the author is not a member of flutter-hackers before re-applying the autosubmit label. Reviewers: If you left a comment approving, please use the "approve" review action instead.

victorsanni · 2026-04-15T00:19:35Z

Thanks for your contribution! This PR has reached completion, however we're not able to merge this PR at the moment due to the Material/Cupertino code freeze (#184093). As soon as the decoupling is complete, we will post a way to port this PR to the new packages to land. In the meantime, I'll convert this PR to a draft and apply a label so that we can quickly find it when the freeze is lifted.

Piinks · 2026-06-24T19:48:13Z

I've marked this PR as not ready to port to flutter/packages yet.
We'll provide instructions to move this change over to material_ui/cupertino_ui once ready to receive PRs. Thank you!

The changes not in the material or cupertino libraries will remain here.

Piinks · 2026-06-25T00:08:32Z

Advice for PR splitting: Since this touches material/cupertino along with other parts of flutter/flutter, it will need to be split up.

If the material/cupertino changes are dependent on the other non-material/cupertino changes in this PR, then the material/cupertino changes will need to wait for them to roll to stable before they can be ported over to material_ui/cupertino_ui in flutter/packages (which uses the stable branch).

If that is the case here, consider opening a new PR with the non-material/cupertino changes to move forward with so that waiting period can be reduced. Up to you!

laishere · 2026-06-25T02:12:57Z

@Piinks Thanks for your advice! The splitted PR is #188542

Piinks · 2026-08-18T20:40:18Z

If you would like to return to this, material_ui and cupertino_ui are now accepting contributions. :)

The portions of this PR that affect the cupertino library can be ported over to flutter/packages, although they may have to wait for the changes in rendering to land here and reach stable first.

Guidance and instructions for easily porting over can be found in #188444

laishere · 2026-08-24T04:18:07Z

@Piinks Created new PR at flutter/packages#12565.
It does not require the splitted engine rendering PR to work.

Piinks · 2026-08-24T16:50:23Z

It does not require the splitted engine rendering PR to work.

Can you say more about this? Why is that so?

laishere · 2026-08-25T00:52:08Z

@Piinks Because the rendering PR is all about assertion debug check. It's used to detect similar issues and does not affect the actual functionality.

dkwingsmt · 2026-08-25T19:08:12Z

I confirm that the framework changes are not needed for the new flag to work. The new PR looks good to me. Would you like to convert this PR to contain the remaining framework changes?

Piinks · 2026-08-25T19:26:53Z

Would you like to convert this PR to contain the remaining framework changes?

Good call, also, since these changes were not needed to fix the issue, it would be good to know the motivation for them. :) Seems like maybe a separate issue?

laishere · 2026-08-26T01:48:10Z

It's already separated at #188542

From flutter/flutter#182935 Fixes flutter/flutter#169495 The scale transition in showCupertinoSheet for the underlying route defaulted to FilterQuality.medium, which pushes an implicit `ImageFilterLayer`. Platform views cannot be correctly sampled or transformed by rasterization-based filters. Consequently, they fail to reflect the scale transformation during the transition animation when an `ImageFilterLayer` is present, leading to a broken visual effect where the background scales but the platform view remains at its original size. **Solution:** Added `hasPlatformView` parameter. `false` by default which matches the original behavior. When set to `true`, we use standard `TransformLayer` by setting filterQuality to `null`. ## Pre-Review Checklist

Fix PlatformView scaling in showCupertinoSheet transitions

5b493f4

github-actions Bot added framework flutter/packages/flutter repository. See also f: labels. p: cupertino_ui cupertino_ui package in flutter/packages labels Feb 26, 2026

gemini-code-assist Bot reviewed Feb 26, 2026

View reviewed changes

laishere added 3 commits February 27, 2026 01:32

Refactor filterQuality to enableFilter for simplicity

b76fdd3

Add tests for enableFilter

d7c3c6b

Fix test case naming

c64e8ec

dkwingsmt self-requested a review March 4, 2026 19:19

dkwingsmt reviewed Mar 31, 2026

View reviewed changes

laishere commented Mar 31, 2026

View reviewed changes

Comment thread packages/flutter/lib/src/cupertino/sheet.dart Outdated

dkwingsmt self-requested a review April 1, 2026 18:25

Rename enableFilter to hasPlatformViews; restore public delegateTrans…

75a4126

…ition

dkwingsmt approved these changes Apr 8, 2026

View reviewed changes

dkwingsmt added the CICD Run CI/CD label Apr 8, 2026

Merge branch 'master' into fix_cupertino_sheet_scaling

cccb5cd

github-actions Bot removed the CICD Run CI/CD label Apr 8, 2026

dkwingsmt added autosubmit Merge PR when tree becomes green via auto submit App CICD Run CI/CD labels Apr 8, 2026

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

dkwingsmt requested a review from victorsanni April 8, 2026 07:00

victorsanni marked this pull request as draft April 15, 2026 00:19

victorsanni added the waiting for code freeze This PR is waiting for a code freeze to resolve. label Apr 15, 2026

Piinks added the Decoupling: Not ready to port yet Instructions will be provided when this is ready to move to flutter/packages. label Jun 24, 2026

Piinks added the Decoupling: Split PR The PR will need to be split to separate Material & Cupertino changes label Jun 25, 2026

laishere mentioned this pull request Jun 25, 2026

Add debug check for platform view filter layer conflict #188542

Closed

10 tasks done

Piinks added Decoupling: Port to flutter/packages This PR is ready to be ported to flutter/packages. We will provide instructions to do so. and removed Decoupling: Not ready to port yet Instructions will be provided when this is ready to move to flutter/packages. labels Aug 18, 2026

laishere mentioned this pull request Aug 24, 2026

[cupertino_ui] Fix platform view sheet transitions flutter/packages#12565

Merged

11 tasks done

laishere closed this Sep 9, 2026

Conversation

laishere commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Example usage

Visual Changes

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

laishere commented Feb 26, 2026

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

laishere commented Mar 31, 2026

Uh oh!

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Apr 8, 2026

Uh oh!

victorsanni commented Apr 15, 2026

Uh oh!

Piinks commented Jun 24, 2026

Uh oh!

Piinks commented Jun 25, 2026

Uh oh!

laishere commented Jun 25, 2026

Uh oh!

Piinks commented Aug 18, 2026

Uh oh!

laishere commented Aug 24, 2026

Uh oh!

Piinks commented Aug 24, 2026

Uh oh!

laishere commented Aug 25, 2026

Uh oh!

dkwingsmt commented Aug 25, 2026

Uh oh!

Piinks commented Aug 25, 2026

Uh oh!

laishere commented Aug 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

laishere commented Feb 26, 2026 •

edited

Loading