fix: performance improvements on SpriteBatch APIs

packages/flame/lib/src/cache/images.dart

@@ -45,6 +45,19 @@ class Images {
     _assets[name] = _ImageAsset.fromImage(image);
   }
 
+  /// Returns the image [name] from the cache. If no image with [name] exists
+  /// uses [imageGenerator] to generate and then add the resulting image into
+  /// the cache.
+  /// The cache will assume the ownership of the resulting image, and will
+  /// properly dispose of it at the end.
+  Future<Image> fetchOrGenerate(
+    String name,
+    Future<Image> Function() imageGenerator,
+  ) {
+    return (_assets[name] ??= _ImageAsset.future(imageGenerator()))
+        .retrieveAsync();
+  }
+
   /// Removes the image [name] from the cache.
   ///
   /// No error is raised if the image [name] is not present in the cache.
@@ -126,6 +139,12 @@ class Images {
   /// Whether the cache contains the specified [key] or not.
   bool containsKey(String key) => _assets.containsKey(key);
 
+  String? findKeyForImage(Image image) {
+    return _assets.keys.firstWhere(
+      (k) => _assets[k]?.image?.isCloneOf(image) ?? false,
+    );
+  }
+
   /// Waits until all currently pending image loading operations complete.
   Future<void> ready() {
     return Future.wait(_assets.values.map((asset) => asset.retrieveAsync()));

packages/flame/lib/src/sprite_batch.dart

@@ -129,7 +129,30 @@ class SpriteBatch {
   }
 
   /// The atlas used by the [SpriteBatch].
-  final Image atlas;
+  Image atlas;
+
+  /// The image cache used by the [SpriteBatch] to store image assets.
+  final Images? _imageCache;
+
+  /// When the [_imageCache] isn't specified, the global [Flame.images] is used.
+  Images get imageCache => _imageCache ?? Flame.images;
+
+  /// The root key use by the [SpriteBatch] to store image assets.
+  final String? _imageKey;
+
+  /// When the [_imageKey] isn't specified [imageKey] will return either the key
+  /// for the [atlas] stored in [imageCache] or a key generated from the
+  /// identityHashCode.
+  String get imageKey =>
+      _imageKey ??
+      imageCache.findKeyForImage(atlas) ??
+      'image[${identityHashCode(atlas)}]';
+
+  /// Whether any [BatchItem]s need a flippableAtlas.
+  bool _hasFlips = false;
+
+  /// The status of the atlas image loading operations.
+  bool _atlasReady = true;
 
   /// The default color, used as a background color for a [BatchItem].
   final Color defaultColor;
@@ -159,7 +182,10 @@ class SpriteBatch {
     this.defaultBlendMode = BlendMode.srcOver,
     this.defaultTransform,
     this.useAtlas = true,
-  });
+    Images? imageCache,
+    String? imageKey,
+  })  : _imageCache = imageCache,
+        _imageKey = imageKey;
 
   /// Takes a path of an image, and optional arguments for the SpriteBatch.
   ///
@@ -172,28 +198,45 @@ class SpriteBatch {
     Images? images,
     bool useAtlas = true,
   }) async {
+    final _images = images ?? Flame.images;
     return SpriteBatch(
-      await _generateAtlas(images, path),
+      await _images.load(path),
       defaultColor: defaultColor,
       defaultTransform: defaultTransform ?? RSTransform(1, 0, 0, 0),
       defaultBlendMode: defaultBlendMode,
       useAtlas: useAtlas,
+      imageCache: _images,
+      imageKey: path,
     );
   }
 
-  static Future<Image> _generateAtlas(Images? images, String path) async {
-    final _images = images ?? Flame.images;
-    final image = await _images.load(path);
+  Future<void> _makeFlippedAtlas() async {
+    _hasFlips = true;
+    _atlasReady = false;
+    final key = '$imageKey#with-flips';
+    atlas = await imageCache.fetchOrGenerate(
+      key,
+      () => _generateFlippedAtlas(atlas),
+    );
+    _atlasReady = true;
+  }
+
+  Future<Image> _generateFlippedAtlas(
+    Image image,
+  ) {
     final recorder = PictureRecorder();
     final canvas = Canvas(recorder);
     final _emptyPaint = Paint();
     canvas.drawImage(image, Offset.zero, _emptyPaint);
     canvas.scale(-1, 1);
-    canvas.drawImage(image, Offset(-image.width * 2, 0), _emptyPaint);
+    canvas.drawImage(
+      image,
+      Offset(-image.width.toDouble(), image.height.toDouble()),
+      _emptyPaint,
+    );
 
     final picture = recorder.endRecording();
-    final atlas = picture.toImageSafe(image.width * 2, image.height);
-    return atlas;
+    return picture.toImageSafe(image.width, image.height * 2);
   }
 
   /// Add a new batch item using a RSTransform.
@@ -224,13 +267,18 @@ class SpriteBatch {
       color: color ?? defaultColor,
     );
 
+    if (flip && useAtlas && !_hasFlips) {
+      _hasFlips = true;
+      _makeFlippedAtlas();
+    }
+
     _batchItems.add(batchItem);
 
     _sources.add(
       flip
           ? Rect.fromLTWH(
-              atlas.width - source.left - source.width,
-              source.top,
+              atlas.width - source.right,
+              source.top + source.height,
               source.width,
               source.height,
             )
@@ -315,7 +363,17 @@ class SpriteBatch {
   }) {
     paint ??= _emptyPaint;
 
-    if (!useAtlas) {
+    if (useAtlas && _atlasReady) {
+      canvas.drawAtlas(
+        atlas,
+        _transforms,
+        _sources,
+        _colors,
+        blendMode ?? defaultBlendMode,
+        cullRect,
+        paint,
+      );
+    } else {
       for (final batchItem in _batchItems) {
         paint.blendMode = blendMode ?? paint.blendMode;
 
@@ -331,16 +389,6 @@ class SpriteBatch {
           )
           ..restore();
       }
-    } else {
-      canvas.drawAtlas(
-        atlas,
-        _transforms,
-        _sources,
-        _colors,
-        blendMode ?? defaultBlendMode,
-        cullRect,
-        paint,
-      );
     }
   }
 }