fix!: added integer tileDimension & deprecated tileSize

lib/src/layer/tile_layer/retina_mode.dart

@@ -30,7 +30,7 @@ part of 'tile_layer.dart';
 ///
 /// ---
 ///
-/// Caution is advised when mixing retina mode with different `tileSize`s,
+/// Caution is advised when mixing retina mode with different tile dimensions,
 /// especially when simulating retina mode.
 ///
 /// It is expected that [TileLayer.fallbackUrl] follows the same retina support

lib/src/layer/tile_layer/tile.dart

@@ -14,7 +14,7 @@ class Tile extends StatefulWidget {
   final TileBuilder? tileBuilder;
 
   /// The tile size for the given scale of the map.
-  final double scaledTileSize;
+  final double scaledTileDimension;
 
   /// Reference to the offset of the top-left corner of the bounding rectangle
   /// of the [MapCamera]. The origin will not equal the offset of the top-left
@@ -39,7 +39,7 @@ class Tile extends StatefulWidget {
   /// Creates a new instance of [Tile].
   const Tile({
     super.key,
-    required this.scaledTileSize,
+    required this.scaledTileDimension,
     required this.currentPixelOrigin,
     required this.tileImage,
     required this.tileBuilder,
@@ -70,12 +70,12 @@ class _TileState extends State<Tile> {
   @override
   Widget build(BuildContext context) {
     return Positioned(
-      left: widget.positionCoordinates.x * widget.scaledTileSize -
+      left: widget.positionCoordinates.x * widget.scaledTileDimension -
           widget.currentPixelOrigin.x,
-      top: widget.positionCoordinates.y * widget.scaledTileSize -
+      top: widget.positionCoordinates.y * widget.scaledTileDimension -
           widget.currentPixelOrigin.y,
-      width: widget.scaledTileSize,
-      height: widget.scaledTileSize,
+      width: widget.scaledTileDimension,
+      height: widget.scaledTileDimension,
       child: widget.tileBuilder?.call(context, _tileImage, widget.tileImage) ??
           _tileImage,
     );

lib/src/layer/tile_layer/tile_bounds/tile_bounds.dart

@@ -9,7 +9,7 @@ import 'package:meta/meta.dart';
 abstract class TileBounds {
   /// Reference to the coordinate reference system.
   final Crs crs;
-  final double _tileSize;
+  final int _tileDimension;
   final LatLngBounds? _latLngBounds;
 
   /// Constructor that creates an instance of a subclass of [TileBounds]:
@@ -18,21 +18,21 @@ abstract class TileBounds {
   /// [WrappedTileBounds] if the CRS is wrapped.
   factory TileBounds({
     required Crs crs,
-    required double tileSize,
+    required int tileDimension,
     LatLngBounds? latLngBounds,
   }) {
     if (crs.infinite && latLngBounds == null) {
-      return InfiniteTileBounds._(crs, tileSize, latLngBounds);
+      return InfiniteTileBounds._(crs, tileDimension, latLngBounds);
     } else if (crs.wrapLat == null && crs.wrapLng == null) {
-      return DiscreteTileBounds._(crs, tileSize, latLngBounds);
+      return DiscreteTileBounds._(crs, tileDimension, latLngBounds);
     } else {
-      return WrappedTileBounds._(crs, tileSize, latLngBounds);
+      return WrappedTileBounds._(crs, tileDimension, latLngBounds);
     }
   }
 
   const TileBounds._(
     this.crs,
-    this._tileSize,
+    this._tileDimension,
     this._latLngBounds,
   );
 
@@ -43,18 +43,20 @@ abstract class TileBounds {
   /// parameters.
   bool shouldReplace(
     Crs crs,
-    double tileSize,
+    int tileDimension,
     LatLngBounds? latLngBounds,
   ) =>
-      crs != this.crs || tileSize != _tileSize || latLngBounds != _latLngBounds;
+      crs != this.crs ||
+      tileDimension != _tileDimension ||
+      latLngBounds != _latLngBounds;
 }
 
 /// [TileBounds] that have no limits.
 @immutable
 class InfiniteTileBounds extends TileBounds {
   const InfiniteTileBounds._(
     super.crs,
-    super._tileSize,
+    super._tileDimension,
     super._latLngBounds,
   ) : super._();
 
@@ -69,7 +71,7 @@ class DiscreteTileBounds extends TileBounds {
 
   DiscreteTileBounds._(
     super.crs,
-    super._tileSize,
+    super._tileDimension,
     super._latLngBounds,
   ) : super._();
 
@@ -97,7 +99,7 @@ class DiscreteTileBounds extends TileBounds {
     return DiscreteTileBoundsAtZoom(
       DiscreteTileRange.fromPixelBounds(
         zoom: zoom,
-        tileSize: _tileSize,
+        tileDimension: _tileDimension,
         pixelBounds: pixelBounds,
       ),
     );
@@ -111,7 +113,7 @@ class WrappedTileBounds extends TileBounds {
 
   WrappedTileBounds._(
     super.crs,
-    super._tileSize,
+    super._tileDimension,
     super._latLngBounds,
   ) : super._();
 
@@ -136,30 +138,30 @@ class WrappedTileBounds extends TileBounds {
 
     (int, int)? wrapX;
     if (crs.wrapLng case final wrapLng?) {
-      final wrapXMin =
-          (crs.latLngToPoint(LatLng(0, wrapLng.$1), zoomDouble).x / _tileSize)
-              .floor();
-      final wrapXMax =
-          (crs.latLngToPoint(LatLng(0, wrapLng.$2), zoomDouble).x / _tileSize)
-              .ceil();
+      final wrapXMin = (crs.latLngToPoint(LatLng(0, wrapLng.$1), zoomDouble).x /
+              _tileDimension)
+          .floor();
+      final wrapXMax = (crs.latLngToPoint(LatLng(0, wrapLng.$2), zoomDouble).x /
+              _tileDimension)
+          .ceil();
       wrapX = (wrapXMin, wrapXMax - 1);
     }
 
     (int, int)? wrapY;
     if (crs.wrapLat case final wrapLat?) {
-      final wrapYMin =
-          (crs.latLngToPoint(LatLng(wrapLat.$1, 0), zoomDouble).y / _tileSize)
-              .floor();
-      final wrapYMax =
-          (crs.latLngToPoint(LatLng(wrapLat.$2, 0), zoomDouble).y / _tileSize)
-              .ceil();
+      final wrapYMin = (crs.latLngToPoint(LatLng(wrapLat.$1, 0), zoomDouble).y /
+              _tileDimension)
+          .floor();
+      final wrapYMax = (crs.latLngToPoint(LatLng(wrapLat.$2, 0), zoomDouble).y /
+              _tileDimension)
+          .ceil();
       wrapY = (wrapYMin, wrapYMax - 1);
     }
 
     return WrappedTileBoundsAtZoom(
       tileRange: DiscreteTileRange.fromPixelBounds(
         zoom: zoom,
-        tileSize: _tileSize,
+        tileDimension: _tileDimension,
         pixelBounds: pixelBounds,
       ),
       wrappedAxisIsAlwaysInBounds: _latLngBounds == null,

lib/src/layer/tile_layer/tile_layer.dart

@@ -56,9 +56,25 @@ class TileLayer extends StatefulWidget {
   /// If not `null`, then tiles will pull's WMS protocol requests
   final WMSTileLayerOptions? wmsOptions;
 
-  /// Size for the tile.
-  /// Default is 256
-  late final double tileSize;
+  /// Size in pixels of each tile image
+  ///
+  /// Should be a positive integer power of 2. If not an integer, it may be
+  /// truncated to the nearest integer.
+  ///
+  /// If increasing past 256(px) (default), adjust [zoomOffset] as necessary,
+  /// for example 512px: -1.
+  ///
+  /// Prefer [tileDimension]. If `null` (default), [tileDimension] is used.
+  @Deprecated('`tileSize` is deprecated. Use `tileDimension` instead.')
+  late final double? tileSize;
+
+  /// Size in pixels of each tile image
+  ///
+  /// Should be a positive power of 2. Defaults to 256px.
+  ///
+  /// If increasing past 256(px) (default), adjust [zoomOffset] as necessary,
+  /// for example 512px: -1.
+  late final int tileDimension;
 
   /// The minimum zoom level down to which this layer will be displayed
   /// (inclusive)
@@ -216,7 +232,9 @@ class TileLayer extends StatefulWidget {
     super.key,
     this.urlTemplate,
     this.fallbackUrl,
-    double tileSize = 256,
+    @Deprecated('`tileSize` is deprecated. Use `tileDimension` instead.')
+    double? tileSize,
+    int tileDimension = 256,
     double minZoom = 0,
     double maxZoom = double.infinity,
     int minNativeZoom = 0,
@@ -319,8 +337,15 @@ class TileLayer extends StatefulWidget {
     this.zoomOffset = useSimulatedRetina
         ? (zoomReverse ? zoomOffset - 1.0 : zoomOffset + 1.0)
         : zoomOffset;
-    this.tileSize =
-        useSimulatedRetina ? (tileSize / 2.0).floorToDouble() : tileSize;
+    // Deprecated assignment
+    // ignore: deprecated_member_use_from_same_package
+    this.tileSize = tileSize == null
+        ? null
+        : useSimulatedRetina
+            ? (tileSize / 2).floorToDouble()
+            : tileSize;
+    this.tileDimension =
+        useSimulatedRetina ? tileDimension ~/ 2 : tileDimension;
   }
 
   @override
@@ -346,11 +371,16 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
 
   StreamSubscription<void>? _resetSub;
 
+  // REMOVE once `tileSize` is removed, and replace references with
+  // `widget.tileDimension`
+  // ignore: deprecated_member_use_from_same_package
+  int get _tileDimension => widget.tileSize?.toInt() ?? widget.tileDimension;
+
   @override
   void initState() {
     super.initState();
     _resetSub = widget.reset?.listen(_resetStreamHandler);
-    _tileRangeCalculator = TileRangeCalculator(tileSize: widget.tileSize);
+    _tileRangeCalculator = TileRangeCalculator(tileDimension: _tileDimension);
   }
 
   // This is called on every map movement so we should avoid expensive logic
@@ -379,21 +409,21 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
     var reloadTiles = false;
     if (!_initializedFromMapCamera ||
         _tileBounds.shouldReplace(
-            camera.crs, widget.tileSize, widget.tileBounds)) {
+            camera.crs, _tileDimension, widget.tileBounds)) {
       reloadTiles = true;
       _tileBounds = TileBounds(
         crs: camera.crs,
-        tileSize: widget.tileSize,
+        tileDimension: _tileDimension,
         latLngBounds: widget.tileBounds,
       );
     }
 
     if (!_initializedFromMapCamera ||
-        _tileScaleCalculator.shouldReplace(camera.crs, widget.tileSize)) {
+        _tileScaleCalculator.shouldReplace(camera.crs, _tileDimension)) {
       reloadTiles = true;
       _tileScaleCalculator = TileScaleCalculator(
         crs: camera.crs,
-        tileSize: widget.tileSize,
+        tileDimension: _tileDimension,
       );
     }
 
@@ -408,23 +438,25 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
     var reloadTiles = false;
 
     // There is no caching in TileRangeCalculator so we can just replace it.
-    _tileRangeCalculator = TileRangeCalculator(tileSize: widget.tileSize);
+    _tileRangeCalculator = TileRangeCalculator(tileDimension: _tileDimension);
 
     if (_tileBounds.shouldReplace(
-        _tileBounds.crs, widget.tileSize, widget.tileBounds)) {
+        _tileBounds.crs, _tileDimension, widget.tileBounds)) {
       _tileBounds = TileBounds(
         crs: _tileBounds.crs,
-        tileSize: widget.tileSize,
+        tileDimension: _tileDimension,
         latLngBounds: widget.tileBounds,
       );
       reloadTiles = true;
     }
 
     if (_tileScaleCalculator.shouldReplace(
-        _tileScaleCalculator.crs, widget.tileSize)) {
+      _tileScaleCalculator.crs,
+      _tileDimension,
+    )) {
       _tileScaleCalculator = TileScaleCalculator(
         crs: _tileScaleCalculator.crs,
-        tileSize: widget.tileSize,
+        tileDimension: widget.tileDimension,
       );
     }
 
@@ -520,7 +552,7 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
               // Must be an ObjectKey, not a ValueKey using the coordinates, in
               // case we remove and replace the TileImage with a different one.
               key: ObjectKey(tileRenderer),
-              scaledTileSize: _tileScaleCalculator.scaledTileSize(
+              scaledTileDimension: _tileScaleCalculator.scaledTileDimension(
                 map.zoom,
                 tileRenderer.positionCoordinates.z,
               ),

lib/src/layer/tile_layer/tile_provider/base_tile_provider.dart

@@ -199,7 +199,9 @@ abstract class TileProvider {
           : options.subdomains[
               (coordinates.x + coordinates.y) % options.subdomains.length],
       'r': options.resolvedRetinaMode == RetinaMode.server ? '@2x' : '',
-      'd': options.tileSize.toString(),
+      // ignore: deprecated_member_use_from_same_package
+      'd': options.tileSize?.toInt().toString() ??
+          options.tileDimension.toString(),
       ...options.additionalOptions,
     };
   }
@@ -224,12 +226,15 @@ abstract class TileProvider {
       populateTemplatePlaceholders(
         options.wmsOptions?.getUrl(
               coordinates,
-              options.tileSize.toInt(),
+              // ignore: deprecated_member_use_from_same_package
+              options.tileSize?.toInt() ?? options.tileDimension,
               options.resolvedRetinaMode == RetinaMode.simulation,
             ) ??
             options.urlTemplate ??
             (throw ArgumentError(
-                '`wmsOptions` or `urlTemplate` must be provided to generate a tile URL')),
+              '`wmsOptions` or `urlTemplate` must be provided to generate '
+              'a tile URL',
+            )),
         coordinates,
         options,
       );

lib/src/layer/tile_layer/tile_range.dart

@@ -41,17 +41,17 @@ class DiscreteTileRange extends TileRange {
   /// Calculate a [DiscreteTileRange] by using the pixel bounds.
   factory DiscreteTileRange.fromPixelBounds({
     required int zoom,
-    required double tileSize,
+    required int tileDimension,
     required Bounds<double> pixelBounds,
   }) {
     final Bounds<int> bounds;
     if (pixelBounds.min == pixelBounds.max) {
-      final minAndMax = (pixelBounds.min / tileSize).floor();
+      final minAndMax = (pixelBounds.min / tileDimension).floor();
       bounds = Bounds<int>(minAndMax, minAndMax);
     } else {
       bounds = Bounds<int>(
-        (pixelBounds.min / tileSize).floor(),
-        (pixelBounds.max / tileSize).ceil() - const Point(1, 1),
+        (pixelBounds.min / tileDimension).floor(),
+        (pixelBounds.max / tileDimension).ceil() - const Point(1, 1),
       );
     }
 

lib/src/layer/tile_layer/tile_range_calculator.dart

@@ -7,10 +7,10 @@ import 'package:meta/meta.dart';
 @immutable
 class TileRangeCalculator {
   /// The tile size in pixels.
-  final double tileSize;
+  final int tileDimension;
 
   /// Create a new [TileRangeCalculator] instance.
-  const TileRangeCalculator({required this.tileSize});
+  const TileRangeCalculator({required this.tileDimension});
 
   /// Calculates the visible pixel bounds at the [tileZoom] zoom level when
   /// viewing the map from the [viewingZoom] centered at the [center]. The
@@ -27,7 +27,7 @@ class TileRangeCalculator {
   }) {
     return DiscreteTileRange.fromPixelBounds(
       zoom: tileZoom,
-      tileSize: tileSize,
+      tileDimension: tileDimension,
       pixelBounds: _calculatePixelBounds(
         camera,
         center ?? camera.center,