use immutable buffer for loading asset images (flutter#103496)

Author: Jonah Williams

dev/benchmarks/macrobenchmarks/lib/src/animated_placeholder.dart

@@ -4,6 +4,7 @@
 
 import 'dart:convert';
 import 'dart:ui' as ui show Codec;
+import 'dart:ui';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
@@ -57,11 +58,11 @@ class DelayedBase64Image extends ImageProvider<int> {
   }
 
   @override
-  ImageStreamCompleter load(int key, DecoderCallback decode) {
+  ImageStreamCompleter loadBuffer(int key, DecoderBufferCallback decode) {
     return MultiFrameImageStreamCompleter(
       codec: Future<ui.Codec>.delayed(
         delay,
-        () => decode(base64.decode(data)),
+        () async => decode(await ImmutableBuffer.fromUint8List(base64.decode(data))),
       ),
       scale: 1.0,
     );

dev/benchmarks/microbenchmarks/lib/ui/image_bench.dart

@@ -87,9 +87,7 @@ Future<void> main() async {
     for (int i = 0; i < 10; i += 1) {
       await Future.wait(<Future<ui.ImmutableBuffer>>[
         for (String asset in assets)
-          rootBundle.load(asset).then((ByteData data) {
-            return ui.ImmutableBuffer.fromUint8List(data.buffer.asUint8List());
-          })
+          rootBundle.loadBuffer(asset)
       ]);
     }
     watch.stop();

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

@@ -46,7 +46,26 @@ class NetworkImage extends image_provider.ImageProvider<image_provider.NetworkIm
     final StreamController<ImageChunkEvent> chunkEvents = StreamController<ImageChunkEvent>();
 
     return MultiFrameImageStreamCompleter(
-      codec: _loadAsync(key as NetworkImage, chunkEvents, decode),
+      codec: _loadAsync(key as NetworkImage, chunkEvents, null, decode),
+      chunkEvents: chunkEvents.stream,
+      scale: key.scale,
+      debugLabel: key.url,
+      informationCollector: () => <DiagnosticsNode>[
+        DiagnosticsProperty<image_provider.ImageProvider>('Image provider', this),
+        DiagnosticsProperty<image_provider.NetworkImage>('Image key', key),
+      ],
+    );
+  }
+
+  @override
+  ImageStreamCompleter loadBuffer(image_provider.NetworkImage key, image_provider.DecoderBufferCallback decode) {
+    // Ownership of this controller is handed off to [_loadAsync]; it is that
+    // method's responsibility to close the controller's stream when the image
+    // has been loaded or an error is thrown.
+    final StreamController<ImageChunkEvent> chunkEvents = StreamController<ImageChunkEvent>();
+
+    return MultiFrameImageStreamCompleter(
+      codec: _loadAsync(key as NetworkImage, chunkEvents, decode, null),
       chunkEvents: chunkEvents.stream,
       scale: key.scale,
       debugLabel: key.url,
@@ -77,7 +96,8 @@ class NetworkImage extends image_provider.ImageProvider<image_provider.NetworkIm
   Future<ui.Codec> _loadAsync(
     NetworkImage key,
     StreamController<ImageChunkEvent> chunkEvents,
-    image_provider.DecoderCallback decode,
+    image_provider.DecoderBufferCallback? decode,
+    image_provider.DecoderCallback? decodeDepreacted,
   ) async {
     try {
       assert(key == this);
@@ -111,7 +131,13 @@ class NetworkImage extends image_provider.ImageProvider<image_provider.NetworkIm
         throw Exception('NetworkImage is an empty file: $resolved');
       }
 
-      return decode(bytes);
+      if (decode != null) {
+        final ui.ImmutableBuffer buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
+        return decode(buffer);
+      } else {
+        assert(decodeDepreacted != null);
+        return decodeDepreacted!(bytes);
+      }
     } catch (e) {
       // Depending on where the exception was thrown, the image cache may not
       // have had a chance to track the key in the cache at all.

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

@@ -66,7 +66,24 @@ class NetworkImage
 
     return MultiFrameImageStreamCompleter(
       chunkEvents: chunkEvents.stream,
-      codec: _loadAsync(key as NetworkImage, decode, chunkEvents),
+      codec: _loadAsync(key as NetworkImage, null, decode, chunkEvents),
+      scale: key.scale,
+      debugLabel: key.url,
+      informationCollector: _imageStreamInformationCollector(key),
+    );
+  }
+
+  @override
+  ImageStreamCompleter loadBuffer(image_provider.NetworkImage key, image_provider.DecoderBufferCallback decode) {
+    // Ownership of this controller is handed off to [_loadAsync]; it is that
+    // method's responsibility to close the controller's stream when the image
+    // has been loaded or an error is thrown.
+    final StreamController<ImageChunkEvent> chunkEvents =
+        StreamController<ImageChunkEvent>();
+
+    return MultiFrameImageStreamCompleter(
+      chunkEvents: chunkEvents.stream,
+      codec: _loadAsync(key as NetworkImage, decode, null, chunkEvents),
       scale: key.scale,
       debugLabel: key.url,
       informationCollector: _imageStreamInformationCollector(key),
@@ -93,7 +110,8 @@ class NetworkImage
   // directly in place of the typical `instantiateImageCodec` method.
   Future<ui.Codec> _loadAsync(
     NetworkImage key,
-    image_provider.DecoderCallback decode,
+    image_provider.DecoderBufferCallback? decode,
+    image_provider.DecoderCallback? decodeDepreacted,
     StreamController<ImageChunkEvent> chunkEvents,
   ) async {
     assert(key == this);
@@ -144,7 +162,13 @@ class NetworkImage
             statusCode: request.status!, uri: resolved);
       }
 
-      return decode(bytes);
+      if (decode != null) {
+        final ui.ImmutableBuffer buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
+        return decode(buffer);
+      } else {
+        assert(decodeDepreacted != null);
+        return decodeDepreacted!(bytes);
+      }
     } else {
       // This API only exists in the web engine implementation and is not
       // contained in the analyzer summary for Flutter.

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

@@ -3,7 +3,7 @@
 // found in the LICENSE file.
 
 import 'dart:typed_data' show Uint8List;
-import 'dart:ui' as ui show instantiateImageCodec, Codec;
+import 'dart:ui' as ui show instantiateImageCodec, instantiateImageCodecFromBuffer, Codec, ImmutableBuffer;
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart' show ServicesBinding;
 
@@ -81,6 +81,9 @@ mixin PaintingBinding on BindingBase, ServicesBinding {
 
   /// Calls through to [dart:ui.instantiateImageCodec] from [ImageCache].
   ///
+  /// This method is deprecated. use [instantiateImageCodecFromBuffer] with an
+  /// [ImmutableBuffer] instance instead of this method.
+  ///
   /// The `cacheWidth` and `cacheHeight` parameters, when specified, indicate
   /// the size to decode the image to.
   ///
@@ -97,6 +100,10 @@ mixin PaintingBinding on BindingBase, ServicesBinding {
   /// unnecessary memory usage for images. Callers that wish to display an image
   /// above its native resolution should prefer scaling the canvas the image is
   /// drawn into.
+  @Deprecated(
+    'Use instantiateImageCodecFromBuffer with an ImmutableBuffer instance instead. '
+    'This feature was deprecated after v2.13.0-1.0.pre.',
+  )
   Future<ui.Codec> instantiateImageCodec(
     Uint8List bytes, {
     int? cacheWidth,
@@ -114,6 +121,44 @@ mixin PaintingBinding on BindingBase, ServicesBinding {
     );
   }
 
+  /// Calls through to [dart:ui.instantiateImageCodecFromBuffer] from [ImageCache].
+  ///
+  /// The [buffer] parameter should be an [ui.ImmutableBuffer] instance which can
+  /// be acquired from [ui.ImmutableBuffer.fromUint8List] or [ui.ImmutableBuffer.fromAsset].
+  ///
+  /// The [cacheWidth] and [cacheHeight] parameters, when specified, indicate
+  /// the size to decode the image to.
+  ///
+  /// Both [cacheWidth] and [cacheHeight] must be positive values greater than
+  /// or equal to 1, or null. It is valid to specify only one of `cacheWidth`
+  /// and [cacheHeight] with the other remaining null, in which case the omitted
+  /// dimension will be scaled to maintain the aspect ratio of the original
+  /// dimensions. When both are null or omitted, the image will be decoded at
+  /// its native resolution.
+  ///
+  /// The [allowUpscaling] parameter determines whether the `cacheWidth` or
+  /// [cacheHeight] parameters are clamped to the intrinsic width and height of
+  /// the original image. By default, the dimensions are clamped to avoid
+  /// unnecessary memory usage for images. Callers that wish to display an image
+  /// above its native resolution should prefer scaling the canvas the image is
+  /// drawn into.
+  Future<ui.Codec> instantiateImageCodecFromBuffer(
+    ui.ImmutableBuffer buffer, {
+    int? cacheWidth,
+    int? cacheHeight,
+    bool allowUpscaling = false,
+  }) {
+    assert(cacheWidth == null || cacheWidth > 0);
+    assert(cacheHeight == null || cacheHeight > 0);
+    assert(allowUpscaling != null);
+    return ui.instantiateImageCodecFromBuffer(
+      buffer,
+      targetWidth: cacheWidth,
+      targetHeight: cacheHeight,
+      allowUpscaling: allowUpscaling,
+    );
+  }
+
   @override
   void evict(String asset) {
     super.evict(asset);