getDestinationClipBounds method Null safety

Returns the conservative bounds of the combined result of all clip methods executed within the current save stack of this Canvas object, as measured in the destination coordinate space in which the Picture will be rendered.

Unlike getLocalClipBounds, the bounds are not rounded out to an integer pixel boundary as the Destination coordinate space may not represent pixels if the Picture being constructed will be further transformed when it is rendered or added to a scene. In order to determine the true pixels being affected, those external transforms should be applied first before rounding out the result to integer pixel boundaries. Most typically, Picture objects are rendered in a scene with a scale transform representing the Device Pixel Ratio.

The conservative estimate of the bounds is based on intersecting the bounds of each clip method that was executed with ClipOp.intersect and potentially ignoring any clip method that was executed with ClipOp.difference. The ClipOp argument is only present on the clipRect method.

To understand how the bounds estimate can be conservative, consider the following two clip method calls:

void draw(Canvas canvas) {
  canvas.clipPath(Path()
    ..addRect(const Rect.fromLTRB(10, 10, 20, 20))
    ..addRect(const Rect.fromLTRB(80, 80, 100, 100)));
  canvas.clipPath(Path()
    ..addRect(const Rect.fromLTRB(80, 10, 100, 20))
    ..addRect(const Rect.fromLTRB(10, 80, 20, 100)));
  ...
}

After executing both of those calls there is no area left in which to draw because the two paths have no overlapping regions. But, in this case, getClipBounds would return a rectangle from 10, 10 to 100, 100 because it only intersects the bounds of the two path objects to obtain its conservative estimate.

The clip bounds are not affected by the bounds of any enclosing saveLayer call as the engine does not currently guarantee the strict enforcement of those bounds during rendering.

Methods that can change the current clip include clipRect, clipRRect, and clipPath. The restore method can also modify the current clip by restoring it to the same value it had before its associated save or saveLayer call.