feat: Adding bleed option to SpriteBatch

packages/flame/lib/src/sprite_batch.dart

@@ -41,6 +41,7 @@ class BatchItem {
     required this.transform,
     Color? color,
     this.flip = false,
+    this.bleed = 0,
   }) : color = color ?? const Color(0x00000000),
        paint = Paint()..color = color ?? const Color(0x00000000),
        destination = Offset.zero & source.size;
@@ -59,6 +60,12 @@ class BatchItem {
   /// The flip value for this batch item.
   bool flip;
 
+  /// The bleed value for this batch item in pixels.
+  /// When greater than 0, the destination is expanded outward by this amount
+  /// while keeping the source sampling region the same, which helps prevent
+  /// edge artifacts (seams between tiles in a tilemap).
+  double bleed;
+
   /// The color of the batch item (used for building the drawAtlas color list).
   Color color;
 
@@ -305,6 +312,37 @@ class SpriteBatch {
     );
   }
 
+  /// Computes a transform with bleed applied.
+  ///
+  /// The bleed expands the destination rectangle outward by the bleed amount
+  /// in all directions while keeping the source sampling region unchanged.
+  /// This helps prevent edge artifacts (seams between tiles in a tilemap).
+  static RSTransform _computeBleedTransform(
+    RSTransform transform,
+    Rect source,
+    double bleed,
+  ) {
+    if (bleed == 0) {
+      return transform;
+    }
+
+    // Scale factors for width and height with bleed
+    final scaleX = (source.width + bleed * 2) / source.width;
+    final scaleY = (source.height + bleed * 2) / source.height;
+
+    // Apply scale to the rotation/scale components
+    final scos = transform.scos * scaleX;
+    final ssin = transform.ssin * scaleY;
+
+    // Adjust translation to keep centered after scaling
+    // When we scale up, we need to shift back by the bleed amount
+    // adjusted for the current scale and rotation
+    final tx = transform.tx - bleed * scaleX;
+    final ty = transform.ty - bleed * scaleY;
+
+    return RSTransform(scos, ssin, tx, ty);
+  }
+
   /// Ensures that the given [handle] exists and returns its slot.
   int _requireSlot(int handle) {
     final slot = _handleToSlot[handle];
@@ -338,7 +376,13 @@ class SpriteBatch {
     }
 
     _sources[slot] = _resolveSourceForAtlas(currentBatchItem);
-    _transforms[slot] = currentBatchItem.transform;
+
+    // Apply bleed to the updated transform
+    _transforms[slot] = _computeBleedTransform(
+      currentBatchItem.transform,
+      currentBatchItem.source,
+      currentBatchItem.bleed,
+    );
 
     // If color is not explicitly provided, store transparent.
     _colors[slot] = color ?? _defaultColor;
@@ -360,6 +404,11 @@ class SpriteBatch {
   /// The [color] parameter allows you to render a color behind the batch item,
   /// as a background color.
   ///
+  /// The [bleed] parameter expands the destination rectangle outward by this
+  /// amount in all directions while keeping the source sampling region the
+  /// same. This helps prevent edge artifacts (seams between tiles in a
+  /// tilemap). For best results, the atlas should have padding between sprites.
+  ///
   /// The [add] method may be a simpler way to add a batch item to the batch.
   /// However, if there is a way to factor out the computations of the sine and
   /// cosine of the rotation so that they can be reused over multiple calls to
@@ -370,6 +419,7 @@ class SpriteBatch {
     RSTransform? transform,
     bool flip = false,
     Color? color,
+    double bleed = 0,
   }) {
     final handle = _allocateHandle();
 
@@ -378,6 +428,7 @@ class SpriteBatch {
       transform: transform ??= defaultTransform ?? RSTransform(1, 0, 0, 0),
       flip: flip,
       color: color ?? defaultColor,
+      bleed: bleed,
     );
 
     if (flip && useAtlas && _flippedAtlasStatus.isNone) {
@@ -391,7 +442,14 @@ class SpriteBatch {
 
     _batchItems.add(batchItem);
     _sources.add(_resolveSourceForAtlas(batchItem));
-    _transforms.add(batchItem.transform);
+
+    // Apply bleed to the transform
+    final bleedTransform = _computeBleedTransform(
+      batchItem.transform,
+      batchItem.source,
+      batchItem.bleed,
+    );
+    _transforms.add(bleedTransform);
 
     // If color is not explicitly provided, store transparent.
     _colors.add(color ?? _defaultColor);
@@ -410,6 +468,11 @@ class SpriteBatch {
   /// The [color] parameter allows you to render a color behind the batch item,
   /// as a background color.
   ///
+  /// The [bleed] parameter expands the destination rectangle outward by this
+  /// amount in all directions while keeping the source sampling region the
+  /// same. This helps prevent edge artifacts (seams between tiles in a
+  /// tilemap). For best results, the atlas should have padding between sprites.
+  ///
   /// This method creates a new [RSTransform] based on the given transform
   /// arguments. If many [RSTransform] objects are being created and there is a
   /// way to factor out the computations of the sine and cosine of the rotation
@@ -425,6 +488,7 @@ class SpriteBatch {
     Vector2? offset,
     bool flip = false,
     Color? color,
+    double bleed = 0,
   }) {
     anchor ??= Vector2.zero();
     offset ??= Vector2.zero();
@@ -452,6 +516,7 @@ class SpriteBatch {
       transform: transform,
       flip: flip,
       color: color,
+      bleed: bleed,
     );
   }
 

packages/flame/test/sprite_batch_test.dart

@@ -66,6 +66,89 @@
       );
     });
 
+    test('can add batch item with bleed', () {
+      final image = _MockImage();
+      when(() => image.width).thenReturn(100);
+      when(() => image.height).thenReturn(100);
+      final spriteBatch = SpriteBatch(image);
+      const source = Rect.fromLTWH(0, 0, 10, 10);
+      const bleed = 2.0;
+
+      final index = spriteBatch.add(
+        source: source,
+        bleed: bleed,
+      );
+      final batchItem = spriteBatch.getBatchItem(index);
+
+      expect(batchItem.bleed, bleed);
+    });
+
+    test('bleed scales the transform correctly', () {
+      final image = _MockImage();
+      when(() => image.width).thenReturn(100);
+      when(() => image.height).thenReturn(100);
+      final spriteBatch = SpriteBatch(image);
+      const source = Rect.fromLTWH(0, 0, 10, 10);
+      const bleed = 1.0;
+      // Expected scale: (10 + 2*1) / 10 = 1.2
+      const expectedScale = 1.2;
+
+      spriteBatch.add(
+        source: source,
+        bleed: bleed,
+      );
+
+      // The stored transform should be scaled by the bleed factor
+      final storedTransform = spriteBatch.transforms.first;
+      expect(storedTransform.scos, closeTo(expectedScale, 0.001));
+      expect(storedTransform.ssin, closeTo(0.0, 0.001));
+    });
+
+    test('bleed is preserved when replacing transform', () {
+      final image = _MockImage();
+      when(() => image.width).thenReturn(100);
+      when(() => image.height).thenReturn(100);
+      final spriteBatch = SpriteBatch(image);
+      const source = Rect.fromLTWH(0, 0, 10, 10);
+      const bleed = 2.0;
+
+      final index = spriteBatch.add(
+        source: source,
+        bleed: bleed,
+      );
+
+      // Replace the transform - bleed should be re-applied
+      spriteBatch.replace(index, transform: RSTransform(2, 0, 5, 5));
+
+      final batchItem = spriteBatch.getBatchItem(index);
+      expect(batchItem.bleed, bleed);
+
+      // The new transform should have bleed applied
+      // Original: scos=2, with bleed scale 1.4 -> scos=2.8
+      const expectedScale = (10 + 2 * bleed) / 10; // 1.4
+      final storedTransform = spriteBatch.transforms.first;
+      expect(storedTransform.scos, closeTo(2 * expectedScale, 0.001));
+    });
+
+    test('zero bleed does not affect transform', () {
+      final image = _MockImage();
+      when(() => image.width).thenReturn(100);
+      when(() => image.height).thenReturn(100);
+      final spriteBatch = SpriteBatch(image);
+      const source = Rect.fromLTWH(0, 0, 10, 10);
+
+      spriteBatch.add(
+        source: source,
+        bleed: 0,
+      );
+
+      final storedTransform = spriteBatch.transforms.first;
+      expect(storedTransform.scos, closeTo(1.0, 0.001));
+      expect(storedTransform.ssin, closeTo(0.0, 0.001));
+      expect(storedTransform.tx, closeTo(0.0, 0.001));
+      expect(storedTransform.ty, closeTo(0.0, 0.001));
+    });
+
     const margin = 2.0;
     const tileSize = 6.0;
 
@@ -128,5 +211,41 @@
       backgroundColor: const Color(0xFFFFFFFF),
       goldenFile: '_goldens/sprite_batch_test_2.png',
     );
+
+    testGolden(
+      'can render a batch with bleed',
+      (game, tester) async {
+        final spriteSheet = await loadImage('alphabet.png');
+        final spriteBatch = SpriteBatch(spriteSheet);
+
+        // Source is a single tile - we want to see if bleed expands the render
+        const source = Rect.fromLTWH(3 * tileSize, 0, tileSize, tileSize);
+        const bleed = 1.0;
+
+        // Add sprite without bleed (left)
+        spriteBatch.add(
+          source: source,
+          offset: Vector2.all(margin),
+          scale: 2.0,
+        );
+
+        // Add sprite with bleed (right) - should appear slightly larger
+        spriteBatch.add(
+          source: source,
+          offset: Vector2(2 * margin + tileSize * 2 + 4, margin),
+          scale: 2.0,
+          bleed: bleed,
+        );
+
+        game.add(
+          SpriteBatchComponent(
+            spriteBatch: spriteBatch,
+          ),
+        );
+      },
+      size: Vector2(4 * margin + 4 * tileSize + 4, 3 * margin + 2 * tileSize),
+      backgroundColor: const Color(0xFFFFFFFF),
+      goldenFile: '_goldens/sprite_batch_test_3.png',
+    );
   });
 }