paintImage function

void paintImage({
  1. required Canvas canvas,
  2. required Rect rect,
  3. required Image image,
  4. String? debugImageLabel,
  5. double scale = 1.0,
  6. double opacity = 1.0,
  7. ColorFilter? colorFilter,
  8. BoxFit? fit,
  9. Alignment alignment = Alignment.center,
  10. Rect? centerSlice,
  11. ImageRepeat repeat = ImageRepeat.noRepeat,
  12. bool flipHorizontally = false,
  13. bool invertColors = false,
  14. FilterQuality filterQuality = FilterQuality.medium,
  15. bool isAntiAlias = false,
  16. BlendMode blendMode = BlendMode.srcOver,
})

Paints an image into the given rectangle on the canvas.

The arguments have the following meanings:

  • canvas: The canvas onto which the image will be painted.

  • rect: The region of the canvas into which the image will be painted. The image might not fill the entire rectangle (e.g., depending on the fit). If rect is empty, nothing is painted.

  • image: The image to paint onto the canvas.

  • scale: The number of image pixels for each logical pixel.

  • opacity: The opacity to paint the image onto the canvas with.

  • colorFilter: If non-null, the color filter to apply when painting the image.

  • fit: How the image should be inscribed into rect. If null, the default behavior depends on centerSlice. If centerSlice is also null, the default behavior is BoxFit.scaleDown. If centerSlice is non-null, the default behavior is BoxFit.fill. See BoxFit for details.

  • alignment: How the destination rectangle defined by applying fit is aligned within rect. For example, if fit is BoxFit.contain and alignment is Alignment.bottomRight, the image will be as large as possible within rect and placed with its bottom right corner at the bottom right corner of rect. Defaults to Alignment.center.

  • centerSlice: The image is drawn in nine portions described by splitting the image by drawing two horizontal lines and two vertical lines, where centerSlice describes the rectangle formed by the four points where these four lines intersect each other. (This forms a 3-by-3 grid of regions, the center region being described by centerSlice.) The four regions in the corners are drawn, without scaling, in the four corners of the destination rectangle defined by applying fit. The remaining five regions are drawn by stretching them to fit such that they exactly cover the destination rectangle while maintaining their relative positions. See also Canvas.drawImageNine.

  • repeat: If the image does not fill rect, whether and how the image should be repeated to fill rect. By default, the image is not repeated. See ImageRepeat for details.

  • flipHorizontally: Whether to flip the image horizontally. This is occasionally used with images in right-to-left environments, for images that were designed for left-to-right locales (or vice versa). Be careful, when using this, to not flip images with integral shadows, text, or other effects that will look incorrect when flipped.

  • invertColors: Inverting the colors of an image applies a new color filter to the paint. If there is another specified color filter, the invert will be applied after it. This is primarily used for implementing smart invert on iOS.

  • filterQuality: Use this to change the quality when scaling an image. Defaults to FilterQuality.medium.

See also:

Implementation

void paintImage({
  required Canvas canvas,
  required Rect rect,
  required ui.Image image,
  String? debugImageLabel,
  double scale = 1.0,
  double opacity = 1.0,
  ColorFilter? colorFilter,
  BoxFit? fit,
  Alignment alignment = Alignment.center,
  Rect? centerSlice,
  ImageRepeat repeat = ImageRepeat.noRepeat,
  bool flipHorizontally = false,
  bool invertColors = false,
  FilterQuality filterQuality = FilterQuality.medium,
  bool isAntiAlias = false,
  BlendMode blendMode = BlendMode.srcOver,
}) {
  assert(
    image.debugGetOpenHandleStackTraces()?.isNotEmpty ?? true,
    'Cannot paint an image that is disposed.\n'
    'The caller of paintImage is expected to wait to dispose the image until '
    'after painting has completed.',
  );
  if (rect.isEmpty) {
    return;
  }
  Size outputSize = rect.size;
  Size inputSize = Size(image.width.toDouble(), image.height.toDouble());
  Offset? sliceBorder;
  if (centerSlice != null) {
    sliceBorder = inputSize / scale - centerSlice.size as Offset;
    outputSize = outputSize - sliceBorder as Size;
    inputSize = inputSize - sliceBorder * scale as Size;
  }
  fit ??= centerSlice == null ? BoxFit.scaleDown : BoxFit.fill;
  assert(centerSlice == null || (fit != BoxFit.none && fit != BoxFit.cover));
  final FittedSizes fittedSizes = applyBoxFit(fit, inputSize / scale, outputSize);
  final Size sourceSize = fittedSizes.source * scale;
  Size destinationSize = fittedSizes.destination;
  if (centerSlice != null) {
    outputSize += sliceBorder!;
    destinationSize += sliceBorder;
    // We don't have the ability to draw a subset of the image at the same time
    // as we apply a nine-patch stretch.
    assert(sourceSize == inputSize, 'centerSlice was used with a BoxFit that does not guarantee that the image is fully visible.');
  }

  if (repeat != ImageRepeat.noRepeat && destinationSize == outputSize) {
    // There's no need to repeat the image because we're exactly filling the
    // output rect with the image.
    repeat = ImageRepeat.noRepeat;
  }
  final Paint paint = Paint()..isAntiAlias = isAntiAlias;
  if (colorFilter != null) {
    paint.colorFilter = colorFilter;
  }
  paint.color = Color.fromRGBO(0, 0, 0, clampDouble(opacity, 0.0, 1.0));
  paint.filterQuality = filterQuality;
  paint.invertColors = invertColors;
  paint.blendMode = blendMode;
  final double halfWidthDelta = (outputSize.width - destinationSize.width) / 2.0;
  final double halfHeightDelta = (outputSize.height - destinationSize.height) / 2.0;
  final double dx = halfWidthDelta + (flipHorizontally ? -alignment.x : alignment.x) * halfWidthDelta;
  final double dy = halfHeightDelta + alignment.y * halfHeightDelta;
  final Offset destinationPosition = rect.topLeft.translate(dx, dy);
  final Rect destinationRect = destinationPosition & destinationSize;

  // Set to true if we added a saveLayer to the canvas to invert/flip the image.
  bool invertedCanvas = false;
  // Output size and destination rect are fully calculated.

  // Implement debug-mode and profile-mode features:
  //  - cacheWidth/cacheHeight warning
  //  - debugInvertOversizedImages
  //  - debugOnPaintImage
  //  - Flutter.ImageSizesForFrame events in timeline
  if (!kReleaseMode) {
    // We can use the devicePixelRatio of the views directly here (instead of
    // going through a MediaQuery) because if it changes, whatever is aware of
    // the MediaQuery will be repainting the image anyways.
    // Furthermore, for the memory check below we just assume that all images
    // are decoded for the view with the highest device pixel ratio and use that
    // as an upper bound for the display size of the image.
    final double maxDevicePixelRatio = PaintingBinding.instance.platformDispatcher.views.fold(
      0.0,
      (double previousValue, ui.FlutterView view) => math.max(previousValue, view.devicePixelRatio),
    );
    final ImageSizeInfo sizeInfo = ImageSizeInfo(
      // Some ImageProvider implementations may not have given this.
      source: debugImageLabel ?? '<Unknown Image(${image.width}×${image.height})>',
      imageSize: Size(image.width.toDouble(), image.height.toDouble()),
      displaySize: outputSize * maxDevicePixelRatio,
    );
    assert(() {
      if (debugInvertOversizedImages &&
          sizeInfo.decodedSizeInBytes > sizeInfo.displaySizeInBytes + debugImageOverheadAllowance) {
        final int overheadInKilobytes = (sizeInfo.decodedSizeInBytes - sizeInfo.displaySizeInBytes) ~/ 1024;
        final int outputWidth = sizeInfo.displaySize.width.toInt();
        final int outputHeight = sizeInfo.displaySize.height.toInt();
        FlutterError.reportError(FlutterErrorDetails(
          exception: 'Image $debugImageLabel has a display size of '
            '$outputWidth×$outputHeight but a decode size of '
            '${image.width}×${image.height}, which uses an additional '
            '${overheadInKilobytes}KB (assuming a device pixel ratio of '
            '$maxDevicePixelRatio).\n\n'
            'Consider resizing the asset ahead of time, supplying a cacheWidth '
            'parameter of $outputWidth, a cacheHeight parameter of '
            '$outputHeight, or using a ResizeImage.',
          library: 'painting library',
          context: ErrorDescription('while painting an image'),
        ));
        // Invert the colors of the canvas.
        canvas.saveLayer(
          destinationRect,
          Paint()..colorFilter = const ColorFilter.matrix(<double>[
            -1,  0,  0, 0, 255,
             0, -1,  0, 0, 255,
             0,  0, -1, 0, 255,
             0,  0,  0, 1,   0,
          ]),
        );
        // Flip the canvas vertically.
        final double dy = -(rect.top + rect.height / 2.0);
        canvas.translate(0.0, -dy);
        canvas.scale(1.0, -1.0);
        canvas.translate(0.0, dy);
        invertedCanvas = true;
      }
      return true;
    }());
    // Avoid emitting events that are the same as those emitted in the last frame.
    if (!_lastFrameImageSizeInfo.contains(sizeInfo)) {
      final ImageSizeInfo? existingSizeInfo = _pendingImageSizeInfo[sizeInfo.source];
      if (existingSizeInfo == null || existingSizeInfo.displaySizeInBytes < sizeInfo.displaySizeInBytes) {
        _pendingImageSizeInfo[sizeInfo.source!] = sizeInfo;
      }
      debugOnPaintImage?.call(sizeInfo);
      SchedulerBinding.instance.addPostFrameCallback((Duration timeStamp) {
        _lastFrameImageSizeInfo = _pendingImageSizeInfo.values.toSet();
        if (_pendingImageSizeInfo.isEmpty) {
          return;
        }
        developer.postEvent(
          'Flutter.ImageSizesForFrame',
          <String, Object>{
            for (final ImageSizeInfo imageSizeInfo in _pendingImageSizeInfo.values)
              imageSizeInfo.source!: imageSizeInfo.toJson(),
          },
        );
        _pendingImageSizeInfo = <String, ImageSizeInfo>{};
      }, debugLabel: 'paintImage.recordImageSizes');
    }
  }

  final bool needSave = centerSlice != null || repeat != ImageRepeat.noRepeat || flipHorizontally;
  if (needSave) {
    canvas.save();
  }
  if (repeat != ImageRepeat.noRepeat) {
    canvas.clipRect(rect);
  }
  if (flipHorizontally) {
    final double dx = -(rect.left + rect.width / 2.0);
    canvas.translate(-dx, 0.0);
    canvas.scale(-1.0, 1.0);
    canvas.translate(dx, 0.0);
  }
  if (centerSlice == null) {
    final Rect sourceRect = alignment.inscribe(
      sourceSize, Offset.zero & inputSize,
    );
    if (repeat == ImageRepeat.noRepeat) {
      canvas.drawImageRect(image, sourceRect, destinationRect, paint);
    } else {
      for (final Rect tileRect in _generateImageTileRects(rect, destinationRect, repeat)) {
        canvas.drawImageRect(image, sourceRect, tileRect, paint);
      }
    }
  } else {
    canvas.scale(1 / scale);
    if (repeat == ImageRepeat.noRepeat) {
      canvas.drawImageNine(image, _scaleRect(centerSlice, scale), _scaleRect(destinationRect, scale), paint);
    } else {
      for (final Rect tileRect in _generateImageTileRects(rect, destinationRect, repeat)) {
        canvas.drawImageNine(image, _scaleRect(centerSlice, scale), _scaleRect(tileRect, scale), paint);
      }
    }
  }
  if (needSave) {
    canvas.restore();
  }

  if (invertedCanvas) {
    canvas.restore();
  }
}