ImageFilter default tile mode automatic selection breaking change not…

…ice (#11338)

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](https://developers.google.com/style) — 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](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

---------

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

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

@@ -0,0 +1,82 @@
+---
+title: ImageFilter.blur default tile mode automatic selection.
+description: >-
+  If a tile mode wasn't specified in the constructor, ImageFilter.blur will
+  select one based on the rendering context.
+---
+
+## Summary
+
+  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. Now, the default is `null` and specifies automatic
+  selection unless a specific tile mode is specified.
+
+## Background
+
+  `ImageFilter.blur`'s _tile mode_ specifies what happens to edge pixels for
+  the applied filter. There are four options, `TileMode.clamp` (the previous
+  default), `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 the following tile modes
+  based on context:
+
+  * `decal` with save layers and when applied to individual shape draws
+            (drawRect, drawPath, ...)
+  * `mirror` with backdrop filters.
+  * `clamp` for drawImage.
+
+## Migration guide
+
+  Only blur image filters that don't specify an explicit tile mode are
+  impacted by this change. We believe that the new defaults are generally
+  better and would recommend removing any specified blur tile modes.
+
+
+Code before migration:
+
+```dart
+var filter = ui.ImageFilter.blur(sigmaX: 4, sigmaY: 4, tileMode: TileMode.decal);
+```
+
+Code after migration:
+
+```dart
+var filter = ui.ImageFilter.blur(sigmaX: 4, sigmaY: 4);
+```
+
+## Timeline
+
+Landed in version: 3.27.0-1.0.pre.30
+In stable release: Not yet
+
+## References
+
+{% include docs/main-api.md %}
+
+API documentation:
+
+* [`ImageFilter`][]
+* [`TileMode`][]
+
+Relevant issues:
+
+* [Issue #154935][]
+* [Issue #110318][]
+* [Issue #157693][]
+
+Relevant PRs:
+
+* [Change default TileMode for blur ImageFilter objects to null][]
+
+
+[`ImageFilter`]: https://api.flutter.dev/flutter/dart-ui/ImageFilter-class.html
+[`ImageFilter.blur`]: https://api.flutter.dev/flutter/dart-ui/ImageFilter/ImageFilter.blur.html
+[`TileMode`]: https://api.flutter.dev/flutter/dart-ui/TileMode.html
+[Issue #154935]: https://github.com/flutter/flutter/issues/154935
+[Issue #110318]: https://github.com/flutter/flutter/issues/110318
+[Issue #157693]: https://github.com/flutter/flutter/issues/157693
+[Change default TileMode for blur ImageFilter objects to null]: https://github.com/flutter/engine/pull/55552

src/content/release/breaking-changes/index.md

@@ -33,6 +33,7 @@ release, and listed in alphabetical order:
 
 ### Not yet released to stable
 
+* [`ImageFilter.blur` default tile mode automatic selection][]
 * [Localized messages are generated into source, not a synthetic package][]
 * [`.flutter-plugins-dependencies` replaces `.flutter-plugins`][] <!-- Branch cut starts here, below will be in next stable -->
 * [`Color` wide gamut support][]
@@ -42,6 +43,7 @@ release, and listed in alphabetical order:
 * [Set default for SystemUiMode to Edge-to-Edge][]
 * [Deprecate `ThemeData.dialogBackgroundColor` in favor of `DialogThemeData.backgroundColor`][]
 
+[`ImageFilter.blur` default tile mode automatic selection]: /release/breaking-changes/image-filter-blur-tilemode
 [Localized messages are generated into source, not a synthetic package]: /release/breaking-changes/flutter-generate-i10n-source
 [`.flutter-plugins-dependencies` replaces `.flutter-plugins`]: /release/breaking-changes/flutter-plugins-configuration
 [`Color` wide gamut support]: /release/breaking-changes/wide-gamut-framework