instantiateImageCodecFromBuffer function

Future<Codec> instantiateImageCodecFromBuffer(
  1. ImmutableBuffer buffer, {
  2. int? targetWidth,
  3. int? targetHeight,
  4. bool allowUpscaling = true,
})

Instantiates an image Codec.

This method is a convenience wrapper around the ImageDescriptor API, and using ImageDescriptor directly is preferred since it allows the caller to make better determinations about how and whether to use the targetWidth and targetHeight parameters.

The buffer parameter is the binary image data (e.g a PNG or GIF binary data). The data can be for either static or animated images. The following image formats are supported: JPEG, PNG, GIF, Animated GIF, WebP, Animated WebP, BMP, and WBMP. Additional formats may be supported by the underlying platform. Flutter will attempt to call platform API to decode unrecognized formats, and if the platform API supports decoding the image Flutter will be able to render it.

The buffer will be disposed by this method once the codec has been created, so the caller must relinquish ownership of the buffer when they call this method.

The targetWidth and targetHeight arguments specify the size of the output image, in image pixels. If they are not equal to the intrinsic dimensions of the image, then the image will be scaled after being decoded. If the allowUpscaling parameter is not set to true, both dimensions will be capped at the intrinsic dimensions of the image, even if only one of them would have exceeded those intrinsic dimensions. If exactly one of these two arguments is specified, then the aspect ratio will be maintained while forcing the image to match the other given dimension. If neither is specified, then the image maintains its intrinsic size.

Scaling the image to larger than its intrinsic size should usually be avoided, since it causes the image to use more memory than necessary. Instead, prefer scaling the Canvas transform. If the image must be scaled up, the allowUpscaling parameter must be set to true.

The returned future can complete with an error if the image decoding has failed.

Compatibility note on the web

When running Flutter on the web, only the CanvasKit renderer supports image resizing capabilities (not the HTML renderer). So if image resizing is critical to your use case, and you're deploying to the web, you should build using the CanvasKit renderer.

Implementation

Future<Codec> instantiateImageCodecFromBuffer(
  ImmutableBuffer buffer, {
  int? targetWidth,
  int? targetHeight,
  bool allowUpscaling = true,
}) {
  return instantiateImageCodecWithSize(
    buffer,
    getTargetSize: (int intrinsicWidth, int intrinsicHeight) {
      if (!allowUpscaling) {
        if (targetWidth != null && targetWidth! > intrinsicWidth) {
          targetWidth = intrinsicWidth;
        }
        if (targetHeight != null && targetHeight! > intrinsicHeight) {
          targetHeight = intrinsicHeight;
        }
      }
      return TargetImageSize(width: targetWidth, height: targetHeight);
    },
  );
}