Clipping, Blend-Modi und Layer-Compositing

Advanced visuals in Flutter rarely come from a single shape. Glow rings, frosted overlays, masked thumbnails, and "cut-out" badges are built by layering several draws and controlling how each new layer combines with what's already on the canvas.

Three tools drive this on a Canvas:

• Clipping — restrict where drawing can land (clipPath, clipRect, clipRRect).
• Blend modes — control the math that merges a new layer with the pixels beneath it (BlendMode on a Paint).
• Layers — saveLayer creates an offscreen buffer so a blend mode applies to a whole group, not just one shape.

This lesson wires all three together.

Inside a CustomPainter.paint, a clip narrows the drawable region. Everything you draw after the clip is masked to that region until the next restore().

• canvas.clipRect(rect) — rectangular clip.
• canvas.clipRRect(rrect) — rounded-rectangle clip (great for card thumbnails).
• canvas.clipPath(path) — arbitrary shape clip.

Always pair clipping with save() / restore() so the clip doesn't leak into later draws.

For non-rectangular masks (tickets, waves, badges), build a Path and pass it to clipPath. The classic ticket shape uses two concave arcs on its sides.

Set doAntiAlias: true (the default) for smooth edges. For animated clips that change every frame, doAntiAlias: false can be a touch faster.

A BlendMode defines the formula combining the source (what you're drawing now) with the destination (pixels already there). The default is BlendMode.srcOver — normal alpha compositing.

Useful families:

• Porter-Duff (geometry/masking): srcIn, dstIn, srcOut, dstATop, clear.
• Separable color math: multiply, screen, overlay, plus (additive glow), difference.

You assign it on the Paint: paint.blendMode = BlendMode.multiply.

Here's the key gotcha: many blend modes (srcIn, dstIn, multiply over transparency, etc.) only behave correctly when there is an explicit layer to act as the destination.

canvas.saveLayer(bounds, paint) allocates an offscreen buffer. Draws between saveLayer and restore accumulate in that buffer; on restore the buffer is composited back using the layer paint's blend mode.

Without saveLayer, a srcIn draw would treat the entire screen as destination — usually erasing more than you intended.

The pattern from the previous scene is the idiom for gradient-filled icons or text masks:

• Draw the opaque mask shape first (it becomes the destination).
• Draw the gradient with BlendMode.srcIn — it survives only where the mask is opaque.

Reverse the roles with dstIn: draw the gradient first, then a shape with dstIn to keep only the gradient under that shape. Choose based on which layer you want to draw last.

BlendMode.plus adds source and destination color channels (clamped to 1.0). Overlapping bright shapes get brighter — perfect for neon glows, sparks, and light bloom.

Combine it with a MaskFilter.blur to soften each shape into a halo. Because plus accumulates, layering several blurred circles produces a convincing glow without any image asset.

To cut a transparent hole through an already-drawn layer, draw a shape with BlendMode.clear. It erases destination pixels (sets alpha to 0) wherever the source covers.

This must happen inside a saveLayer — otherwise clear would punch through everything behind the canvas, including widgets below. The spotlight/overlay-with-cutout effect is the canonical use.

There are two distinct paints in play, and mixing them up is a common bug:

• The per-shape paint (passed to drawCircle, drawRect…) controls how that one shape blends with the current layer's contents.
• The layer paint (passed to saveLayer) controls how the entire finished layer blends back when you restore(), and can apply a group opacity or colorFilter.

Want one slider to fade a whole composite group uniformly? Put the opacity on the layer paint, not on each shape — per-shape opacity would let overlaps show through each other.

A frosted, rounded thumbnail with a gradient sheen combines all three tools in order:

• Clip to a rounded rect so nothing spills past the card.
• saveLayer so the sheen can blend against the photo as a group.
• Draw the photo, then a soft highlight with BlendMode.softLight or overlay.

Order is everything: clip first, open the layer, draw destination, draw blended source, restore, then restore the clip.

Each saveLayer allocates an offscreen texture and forces an extra compositing pass — the single most expensive thing you can do per frame in a painter. Treat it as a tool to reach for deliberately, not a default.

• Pass the tightest possible bounds to saveLayer; a full-screen layer is far costlier than a small one.
• Prefer a plain clipRRect + direct draws when you don't actually need group blending.
• Cache static composites (e.g. via ui.PictureRecorder into a ui.Image) instead of rebuilding the layer every frame.
• Reuse Paint objects; avoid allocating in the hot paint path.

You want to fill some bold text glyphs with a linear gradient inside a CustomPainter, and nothing outside the glyphs should be tinted. Which approach is correct?

You can now compose advanced layered effects on a Canvas:

• Clipping (clipRect/clipRRect/clipPath) restricts where draws land — always wrap in save()/restore().
• Blend modes set how a source merges with the destination: srcIn/dstIn for masking, plus for additive glow, clear for cut-out holes, softLight/overlay for sheen.
• saveLayer gives blend modes a real destination buffer and lets you apply group opacity or color filters via the layer paint.
• Distinguish the layer paint from per-shape paint, draw destination-before-source, and keep layers small and rare for performance.

Reach for layers deliberately, clip when you only need a mask, and cache static composites.