Deprecate the animated image frame cache (#26385)

Disables the cache by default and deprecates the API for setting its
size.

flutter/flutter#26081

packages/flutter/lib/src/painting/binding.dart

@@ -9,7 +9,7 @@ import 'package:flutter/services.dart' show ServicesBinding;
 
 import 'image_cache.dart';
 
-const double _kDefaultDecodedCacheRatioCap = 25.0;
+const double _kDefaultDecodedCacheRatioCap = 0.0;
 
 /// Binding for the painting library.
 ///
@@ -47,16 +47,23 @@ mixin PaintingBinding on BindingBase, ServicesBinding {
   /// The maximum multiple of the compressed image size used when caching an
   /// animated image.
   ///
-  /// By default individual frames of animated images are cached into memory to
-  /// avoid using CPU to re-decode them for every loop in the animation. This
-  /// behavior will result in out-of-memory crashes when decoding large
-  /// (or large numbers of) animated images. Set this value to limit how much
-  /// memory each animated image is allowed to use to cache decoded frames
-  /// compared to its compressed size. For example, setting this to `2.0` means
-  /// that a 400KB GIF would be allowed at most to use 800KB of memory caching
-  /// unessential decoded frames. A setting of `1.0` or less disables all caching
-  /// of unessential decoded frames. See [_kDefaultDecodedCacheRatioCap] for the
-  /// default value.
+  /// Individual frames of animated images can be cached into memory to avoid
+  /// using CPU to re-decode them for every loop in the animation. This behavior
+  /// will result in out-of-memory crashes when decoding large (or large numbers
+  /// of) animated images so is disabled by default. Set this value to control
+  /// how much memory each animated image is allowed to use for caching decoded
+  /// frames compared to its compressed size. For example, setting this to `2.0`
+  /// means that a 400KB GIF would be allowed at most to use 800KB of memory
+  /// caching unessential decoded frames. A setting of `1.0` or less disables
+  /// all caching of unessential decoded frames. See
+  /// [_kDefaultDecodedCacheRatioCap] for the default value.
+  ///
+  /// @deprecated The in-memory cache of decoded frames causes issues with
+  /// memory consumption. Soon this API and the in-memory cache will be removed.
+  /// See
+  /// [flutter/flutter#26081](https://github.com/flutter/flutter/issues/26081)
+  /// for more context.
+  @deprecated
   double get decodedCacheRatioCap => _kDecodedCacheRatioCap;
   double _kDecodedCacheRatioCap = _kDefaultDecodedCacheRatioCap;
   /// Changes the maximum multiple of compressed image size used when caching an
@@ -64,15 +71,23 @@ mixin PaintingBinding on BindingBase, ServicesBinding {
   ///
   /// Changing this value only affects new images, not images that have already
   /// been decoded.
+  ///
+  /// @deprecated The in-memory cache of decoded frames causes issues with
+  /// memory consumption. Soon this API and the in-memory cache will be removed.
+  /// See
+  /// [flutter/flutter#26081](https://github.com/flutter/flutter/issues/26081)
+  /// for more context.
+  @deprecated
   set decodedCacheRatioCap(double value) {
     assert (value != null);
     assert (value >= 0.0);
     _kDecodedCacheRatioCap = value;
   }
 
+  // ignore: deprecated_member_use
   /// Calls through to [dart:ui] with [decodedCacheRatioCap] from [ImageCache].
   Future<ui.Codec> instantiateImageCodec(Uint8List list) {
-    return ui.instantiateImageCodec(list, decodedCacheRatioCap: decodedCacheRatioCap);
+    return ui.instantiateImageCodec(list, decodedCacheRatioCap: decodedCacheRatioCap); // ignore: deprecated_member_use
   }
 
   @override

packages/flutter/test/painting/binding_test.dart

@@ -16,7 +16,7 @@ class PaintingBindingSpy extends BindingBase with ServicesBinding, PaintingBindi
   @override
   Future<ui.Codec> instantiateImageCodec(Uint8List list) {
     counter++;
-    return ui.instantiateImageCodec(list, decodedCacheRatioCap: decodedCacheRatioCap);
+    return ui.instantiateImageCodec(list, decodedCacheRatioCap: decodedCacheRatioCap); // ignore: deprecated_member_use
   }
 
   @override
@@ -32,11 +32,11 @@ void main() {
   test('decodedCacheRatio', () async {
     // final PaintingBinding binding = PaintingBinding.instance;
     // Has default value.
-    expect(binding.decodedCacheRatioCap, isNot(null));
+    expect(binding.decodedCacheRatioCap, isNot(null)); // ignore: deprecated_member_use
 
     // Can be set.
-    binding.decodedCacheRatioCap = 1.0;
-    expect(binding.decodedCacheRatioCap, 1.0);
+    binding.decodedCacheRatioCap = 1.0; // ignore: deprecated_member_use
+    expect(binding.decodedCacheRatioCap, 1.0); // ignore: deprecated_member_use
   });
 
   test('instantiateImageCodec used for loading images', () async {