getLocalClipBounds abstract method

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 local coordinate space under which rendering operations are currently performed.

The combined clip results are rounded out to an integer pixel boundary before they are transformed back into the local coordinate space which accounts for the pixel roundoff in rendering operations, particularly when antialiasing. Because the Picture may eventually be rendered into a scene within the context of transforming widgets or layers, the result may thus be overly conservative due to premature rounding. Using the getDestinationClipBounds method combined with the external transforms and rounding in the true device coordinate system will produce more accurate results, but this value may provide a more convenient approximation to compare rendering operations to the established clip.

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, getLocalClipBounds 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.