ImageFilter default tile mode automatic selection breaking change notice #11338

jonahwilliams · 2024-10-28T19:15:20Z

Breaking change notice for flutter/flutter#154935 . Engine PR should land shortly...

Presubmit checklist

This PR is marked as draft with an explanation if not meant to land until a future stable release.
This PR doesn’t contain automatically generated corrections (Grammarly or similar).
This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn’t use i.e. or e.g., and it avoids I and we (first person).
This PR uses semantic line breaks of 80 characters or fewer.

src/content/release/breaking-changes/image-filter-tilemode.md

Co-authored-by: Parker Lougheed <[email protected]>

sfshaza2

Thanks so much for writing this, @jonahwilliams! I have one clarification question.

src/content/release/breaking-changes/image-filter-tilemode.md

sfshaza2 · 2024-10-28T19:33:03Z

src/content/release/breaking-changes/image-filter-tilemode.md

+  was specified. A value of `null` when passed to the filter's constructor
+  specifies automatic selection.


Suggested change

was specified. A value of `null` when passed to the filter's constructor

specifies automatic selection.

Passing a value of `null` to the filter's constructor specifies

automatic selection.

src/content/release/breaking-changes/image-filter-tilemode.md

sfshaza2 · 2024-10-28T19:38:49Z

src/content/release/breaking-changes/image-filter-tilemode.md

+  `Tilemode.repeated`, `TileMode.mirror`, and `TileMode.decal`. The default for
+  ui.ImageFilter is `TileMode.clamp`. We've observed that the behavior of clamp
+  does not match most developer's expections about filter operations. Instead,
+  decal better matches the intuition for saveLayers, as edge pixels are left
+  as transparent black. For backdrop filters, `mirror` is used which prevents
+  falloff on blurs.


So.... why are you giving this advice? Is the default behavior now decal? I think you are saying how the automatic selection process works?

Suggested change

`Tilemode.repeated`, `TileMode.mirror`, and `TileMode.decal`. The default for

ui.ImageFilter is `TileMode.clamp`. We've observed that the behavior of clamp

does not match most developer's expections about filter operations. Instead,

decal better matches the intuition for saveLayers, as edge pixels are left

as transparent black. For backdrop filters, `mirror` is used which prevents

falloff on blurs.

`Tilemode.repeated`, `TileMode.mirror`, and `TileMode.decal`.

Previously, `ImageFilter` defaulted to `clamp` mode if the

behavior wasn't specified, which sometimes surprised developers

as it didn't always match expectations.

As of this change, the filter

automatically selects `decal` mode when using `saveLayers`,

which leave edge pixels as transparent black.

The filter selects `mirror` mode for backdrop filters because

falloff on blurs.

When is the repeated mode used?

That looks better to me too. Repeated is never a default, but can be selected by the developer by specifying it manually when constructing the blur.

There is also drawImage(and variants) that use a default of clamp. And all Canvas.draw methods other than the image (and Atlas) versions will also default to decal.

I replaced this with a list that described the automatic behavior, PTAL?

src/content/release/breaking-changes/image-filter-tilemode.md

sfshaza2 · 2024-10-28T19:54:49Z

/gcbrun

sfshaza2 · 2024-10-28T19:56:15Z

Was this PR in draft mode when I started reviewing it? I didn't notice that. :)

jonahwilliams · 2024-10-28T20:24:25Z

No worries, i appreciate the review as always :)

flar · 2024-10-28T21:19:01Z

src/content/release/breaking-changes/image-filter-tilemode.md

+  The tile mode of a `ImageFilter` declares what happens to edge pixels of
+  the applied filter. There are four options, `TileMode.clamp`,
+  `Tilemode.repeated`, `TileMode.mirror`, and `TileMode.decal`. The default for
+  ui.ImageFilter is `TileMode.clamp`. We've observed that the behavior of clamp


Used to be clamp, or has been clamp, or was previously clamp?

flar · 2024-10-28T21:22:08Z

src/content/release/breaking-changes/image-filter-tilemode.md

+Code after migration:
+
+```dart
+// Set tile mode to old default.


Unless the new defaults look better to you? This makes it sound like developers must specify clamp now, but they may not want to.

flar

Just left some comments.

flar

Some non-blocking suggestions for completeness.

flar · 2024-10-29T19:04:12Z

src/content/release/breaking-changes/image-filter-blur-tilemode.md

+  The `ui.ImageFilter.blur`'s default tile mode is now automatically selected
+  by the backend. Previously `TileMode.clamp` was used unless a different tile
+  mode was specified. Passing a value of `null` to the filter's constructor
+  specifies automatic selection.


Does this imply that you need to manually pass a null to get the behavior? How about:

"Previously the default was clamp unless a different tile mode was specified. Now, the default is null and specifies automatic selection unless a specific tile mode is specified."

flar · 2024-10-29T19:04:57Z

src/content/release/breaking-changes/image-filter-blur-tilemode.md

+
+## Background
+
+  `ImageFilter`'s _tile mode_ specifies what happens to edge pixels for the


Add .blur to mentions of ImageFilter?

flar · 2024-10-29T19:05:39Z

src/content/release/breaking-changes/image-filter-blur-tilemode.md

+  As of this change, the filter automatically selects the following tile modes
+  based on context:
+
+  * `decal` with save layers and when applied to individual draws.


flar · 2024-10-29T19:05:51Z

src/content/release/breaking-changes/image-filter-blur-tilemode.md

+
+## Migration guide
+
+  Only image filters that don't specify an explicit tile mode are


flar · 2024-10-29T19:06:22Z

src/content/release/breaking-changes/image-filter-blur-tilemode.md

+  Only image filters that don't specify an explicit tile mode are
+  impacted by this change. In these cases, you can specify an explicit tile
+  mode to retain the prior behavior. However, we believe the automatic
+  selection of behavior will be a superior choice in most cases.


flar

LGTM again

domesticmouse

PTAL @sfshaza2

domesticmouse · 2024-10-30T02:27:26Z

src/content/release/breaking-changes/image-filter-blur-tilemode.md

+
+```dart
+// Set tile mode to old default.
+var filter = ui.ImageFilter.blur(sigmaX: 4, sigmaY: 4, tileMode: TileMode.clamp);


Should this be turned into a lint with a fix to maintain consistent behavior?

We want folks to use the automatic selection though and not provide a default. maybe this section isn't clear and we should just not include it?

That intent wasn't obvious from my reading, nor was the work that has gone into creating this proposal. I'm happy to work with y'all to build a proposal that better communicates what you are attempting to achieve this, if that would be helpful. Otherwise I can suggest some minor edits?

I mentioned this confusion in an earlier comment. I think this part of the section needs to indicate that it is optional and only needed if the developer preferred the previous behavior. I think it might be worthwhile to include it if the comment in the "after" section made it clear that nothing needs to be done, but if you really want the old behavior then this is the way to restore it. There has to be a concise way to express that the change is optional and probably not desired, but here it is if you need it.

sfshaza2

This PR is better but still seems to cause some confusion. Can we land it?

jonahwilliams · 2024-10-31T22:10:11Z

I was waiting for some FYI that the website infra was working again.

sfshaza2 · 2024-10-31T22:17:32Z

/gcbrun

sfshaza2 · 2024-10-31T22:17:46Z

@jonahwilliams, the website build is working again!

flutter-website-bot · 2024-10-31T22:21:31Z

Visit the preview URL for this PR (updated for commit c24df86):

https://flutter-docs-prod--pr11338-add-tile-mode-breaking-chan-skjvf1ad.web.app

breakig change foo.

5eaeb31

jonahwilliams mentioned this pull request Oct 28, 2024

Change default TileMode for blur ImageFilter objects to null flutter/engine#55552

Merged

do link thingy.

f50f152

parlough reviewed Oct 28, 2024

View reviewed changes

src/content/release/breaking-changes/image-filter-tilemode.md Outdated Show resolved Hide resolved

Update src/content/release/breaking-changes/image-filter-tilemode.md

3e78374

Co-authored-by: Parker Lougheed <[email protected]>

sfshaza2 reviewed Oct 28, 2024

View reviewed changes

flar reviewed Oct 28, 2024

View reviewed changes

jonahwilliams added 2 commits October 29, 2024 09:33

++

06dce06

reformat

bfa53e6

jonahwilliams marked this pull request as ready for review October 29, 2024 16:43

jonahwilliams requested a review from a team as a code owner October 29, 2024 16:43

jonahwilliams requested review from domesticmouse and MaryaBelanger October 29, 2024 16:43

flar approved these changes Oct 29, 2024

View reviewed changes

++

e92ca5f

flar approved these changes Oct 29, 2024

View reviewed changes

domesticmouse approved these changes Oct 30, 2024

View reviewed changes

flar mentioned this pull request Oct 30, 2024

Evaluate ImageFilter.blur tileMode behaviors flutter/flutter#157841

Open

sfshaza2 approved these changes Oct 31, 2024

View reviewed changes

jonahwilliams added 2 commits October 31, 2024 15:46

Add version and index link.

3128374

Merge branch 'main' into add_tile_mode_breaking_change

c24df86

jonahwilliams merged commit 547da8f into flutter:main Nov 1, 2024
9 checks passed

jonahwilliams deleted the add_tile_mode_breaking_change branch November 1, 2024 20:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ImageFilter default tile mode automatic selection breaking change notice #11338

ImageFilter default tile mode automatic selection breaking change notice #11338

jonahwilliams commented Oct 28, 2024

sfshaza2 left a comment

sfshaza2 Oct 28, 2024

jonahwilliams Oct 29, 2024

sfshaza2 Oct 28, 2024

flar Oct 28, 2024

jonahwilliams Oct 29, 2024

sfshaza2 commented Oct 28, 2024

sfshaza2 commented Oct 28, 2024

jonahwilliams commented Oct 28, 2024

flar Oct 28, 2024

flar Oct 28, 2024

flar left a comment

flar left a comment

flar Oct 29, 2024

flar Oct 29, 2024

flar Oct 29, 2024

flar Oct 29, 2024

flar Oct 29, 2024

flar left a comment

domesticmouse left a comment

domesticmouse Oct 30, 2024

jonahwilliams Oct 30, 2024

domesticmouse Oct 30, 2024

flar Oct 30, 2024

sfshaza2 left a comment

jonahwilliams commented Oct 31, 2024

sfshaza2 commented Oct 31, 2024

sfshaza2 commented Oct 31, 2024

flutter-website-bot commented Oct 31, 2024 •

edited

Loading

		was specified. A value of `null` when passed to the filter's constructor
		specifies automatic selection.


		## Background

		`ImageFilter`'s _tile mode_ specifies what happens to edge pixels for the


		## Migration guide

		Only image filters that don't specify an explicit tile mode are

ImageFilter default tile mode automatic selection breaking change notice #11338

ImageFilter default tile mode automatic selection breaking change notice #11338

Conversation

jonahwilliams commented Oct 28, 2024

Presubmit checklist

sfshaza2 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sfshaza2 commented Oct 28, 2024

sfshaza2 commented Oct 28, 2024

jonahwilliams commented Oct 28, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flar left a comment

Choose a reason for hiding this comment

flar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flar left a comment

Choose a reason for hiding this comment

domesticmouse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sfshaza2 left a comment

Choose a reason for hiding this comment

jonahwilliams commented Oct 31, 2024

sfshaza2 commented Oct 31, 2024

sfshaza2 commented Oct 31, 2024

flutter-website-bot commented Oct 31, 2024 • edited Loading

flutter-website-bot commented Oct 31, 2024 •

edited

Loading