feat: added PolygonLayer.painterFillMethod (#2081)

Author: JaffaKetchup

lib/src/layer/polygon_layer/painter.dart

@@ -38,6 +38,9 @@ class _PolygonPainter<R extends Object> extends CustomPainter
   /// See [PolygonLayer.debugAltRenderer]
   final bool debugAltRenderer;
 
+  /// See [PolygonLayer.painterFillMethod]
+  final PolygonPainterFillMethod painterFillMethod;
+
   /// See [PolygonLayer.invertedFill]
   final Color? invertedFill;
 
@@ -55,6 +58,7 @@ class _PolygonPainter<R extends Object> extends CustomPainter
     required this.drawLabelsLast,
     required this.debugAltRenderer,
     required this.camera,
+    required this.painterFillMethod,
     required this.invertedFill,
     required this.hitNotifier,
   }) : bounds = camera.visibleBounds {
@@ -70,20 +74,7 @@ class _PolygonPainter<R extends Object> extends CustomPainter
   /// inverted fill.
   static const _minMaxLatitude = [LatLng(90, 0), LatLng(-90, 0)];
 
-  /// Whether to use `PathFillType.evenOdd` (true) or `Path.combine` (false).
-  ///
-  ///  * `Path.combine` doesn't work & isn't stable/consistent on web
-  ///  * `evenOdd` gives broken results when polygons intersect when inverted
-  ///  * `Path.combine` has slightly worse performance than `evenOdd`
-  ///
-  /// The best option is to use `evenOdd` on web, as it at least works
-  /// sometimes. On native, we use `Path.combine` when inverted filling, or
-  /// `evenOdd` otherwise.
-  ///
-  /// See https://github.com/fleaflet/flutter_map/pull/2046.
-  late final _useEvenOdd = kIsWeb || invertedFill == null;
-
-  /// Do we also remove the holes from the inverted map?
+  /// Do we remove the holes from the inverted map?
   /// Should be `true`.
   static const _invertedHoles = true;
 
@@ -284,7 +275,7 @@ class _PolygonPainter<R extends Object> extends CustomPainter
       // ignore: dead_code
       if (!_fillInvertedHoles) return;
 
-      if (_useEvenOdd) {
+      if (painterFillMethod == PolygonPainterFillMethod.evenOdd) {
         invertedHolePaths.addPolygon(offsets, true);
         return;
       }
@@ -296,7 +287,7 @@ class _PolygonPainter<R extends Object> extends CustomPainter
     }
 
     void unfillPolygon(List<Offset> offsets) {
-      if (_useEvenOdd) {
+      if (painterFillMethod == PolygonPainterFillMethod.evenOdd) {
         filledPath.fillType = PathFillType.evenOdd;
         filledPath.addPolygon(offsets, true);
         return;
@@ -585,7 +576,9 @@ class _PolygonPainter<R extends Object> extends CustomPainter
       triangles != oldDelegate.triangles ||
       camera != oldDelegate.camera ||
       bounds != oldDelegate.bounds ||
+      painterFillMethod != oldDelegate.painterFillMethod ||
       invertedFill != oldDelegate.invertedFill ||
+      debugAltRenderer != oldDelegate.debugAltRenderer ||
       drawLabelsLast != oldDelegate.drawLabelsLast ||
       polygonLabels != oldDelegate.polygonLabels ||
       hitNotifier != oldDelegate.hitNotifier;

lib/src/layer/polygon_layer/polygon_layer.dart

@@ -23,6 +23,36 @@ part 'painter.dart';
 part 'polygon.dart';
 part 'projected_polygon.dart';
 
+/// The method used by the painter to fill polygons and resolve overlaps &
+/// intersections
+///
+/// Each method has its own advantages and disadvantages.
+enum PolygonPainterFillMethod {
+  /// Uses `PathFillType.evenOdd` with `Path().addPolygon`
+  ///
+  /// This gives the best performance, and works on the web. However, it yields
+  /// unintended results in certain edge cases when polygons intersect when
+  /// [PolygonLayer.invertedFill] is used, or when polygon holes intersect with
+  /// other holes.
+  evenOdd,
+
+  /// Uses `Path.combine`
+  ///
+  /// This always gives the best results on non-web platforms. However, it
+  /// always yields unintended results on the web (due to a Flutter issue), and
+  /// has slightly worse performance.
+  ///
+  /// The hit to performance is unlikely to be significant or even noticable in
+  /// many applications, but applications drawing many polygons may see a slow
+  /// of about 2ms (as tested in the example app's stress test). Profile your
+  /// project to determine whether switching methods is suitable, especially if
+  /// there is no visual difference.
+  ///
+  /// See https://github.com/flutter/flutter/issues/124675 for the Flutter issue
+  /// preventing this method from working on the web.
+  pathCombine,
+}
+
 /// A polygon layer for [FlutterMap].
 @immutable
 base class PolygonLayer<R extends Object>
@@ -78,15 +108,25 @@ base class PolygonLayer<R extends Object>
   /// Defaults to `false`.
   final bool drawInSingleWorld;
 
+  /// The method used by the painter to fill polygons and resolve overlaps &
+  /// intersections
+  ///
+  /// See documentation on each value in [PolygonPainterFillMethod] for more
+  /// advantages and disadvantages of each method.
+  ///
+  /// Defaults to [PolygonPainterFillMethod.evenOdd] on web &
+  /// [PolygonPainterFillMethod.pathCombine] otherwise.
+  final PolygonPainterFillMethod painterFillMethod;
+
   /// Color to apply to the map where not covered by a polygon
   ///
   /// > [!WARNING]
   /// > On the web, inverted filling may not work as expected in some cases.
   /// > It will not match the behaviour seen on native platforms. Avoid allowing
   /// > polygons to intersect, and avoid using holes within polygons.
-  /// > This is due to multiple limitations/bugs within Flutter. See the
-  /// > [online documentation](docs.fleaflet.dev/layers/polygon-layer#inverted-filling)
-  /// > for more info.
+  /// > This is because [PolygonPainterFillMethod.evenOdd] must be used on the
+  /// > web, which (due to Flutter issues), does not properly support this
+  /// > functionality.
   final Color? invertedFill;
 
   /// {@macro fm.lhn.layerHitNotifier.usage}
@@ -101,9 +141,12 @@ base class PolygonLayer<R extends Object>
     this.polygonCulling = true,
     this.polygonLabels = true,
     this.drawLabelsLast = false,
+    this.drawInSingleWorld = false,
+    this.painterFillMethod = kIsWeb
+        ? PolygonPainterFillMethod.evenOdd
+        : PolygonPainterFillMethod.pathCombine,
     this.invertedFill,
     this.hitNotifier,
-    this.drawInSingleWorld = false,
     super.simplificationTolerance,
   }) : super();
 
@@ -222,6 +265,7 @@ class _PolygonLayerState<R extends Object> extends State<PolygonLayer<R>>
           camera: camera,
           polygonLabels: widget.polygonLabels,
           drawLabelsLast: widget.drawLabelsLast,
+          painterFillMethod: widget.painterFillMethod,
           invertedFill: widget.invertedFill,
           debugAltRenderer: widget.debugAltRenderer,
           hitNotifier: widget.hitNotifier,