# Clipping Fundamentals: Canvas Clip Stack vs. Layer + Outline Mask

> Clipping isn't a property of the content being clipped, it's a stencil placed in front of paint operations. Two different mechanisms implement that stencil, and only one of them composes with blend modes and opacity.

**Date:** 2026-10-18T00:00:00.000Z
**Tags:** Canvas, Clipping, Graphics

## The intuition

It's tempting to treat clipping and masking as the same move with two
different APIs: both "cut off the part of this content I don't want."
That's the right outcome for the simple case, and the wrong mental model
the moment the edge gets more interesting than a hard line.

* A clip is a **yes/no test**: for every pixel a draw call tries to
  touch, the clip stack asks "is this point inside the shape," and the
  answer is binary. There's no such thing as a pixel that's 60% clipped.
* A mask is an **alpha multiply**: it takes whatever's already rendered
  and scales its alpha by a second image's alpha, pixel for pixel. That
  second image can carry any alpha value from 0 to 1, a gradient, a blur,
  a photo's own luminance, not just "shape" or "not shape."
* Clipping is resolved *before* a draw call paints anything, as a
  restriction on where it's allowed to write. Masking is resolved *as* a
  blend, against content that's already fully painted.

Those two mechanisms happen to produce identical pixels in one specific
case: an opaque shape with a hard edge. That overlap is exactly why they
get treated as interchangeable, right up until you need a soft edge and
discover one of them structurally can't give you one.

* [BlendMode vs CompositingStrategy: It's Not a Fence, It's a Different Canvas](/blend-mode-and-compositing-strategy) — DstIn, SrcIn, and the Offscreen layer this post's masking technique builds on, explained from the blend-formula side.

* [Modifier Order Matters: It's a Wrapper Chain, Not a Property Bag](/compose-modifier-order) — Why clip() has to sit on the outside of background() or border() to actually cut them, the wrapper-chain reasoning this post's clip stack relies on.

## Concrete example: fading a photo's edge

Reach for `clipPath` first, because it's the obvious tool for "cut this
to a shape":

```kotlin
// Canvas clip stack: clipPath pushes a binary stencil onto the canvas.
// Every pixel inside the path is fully visible, every pixel outside it
// is fully gone. There is no third option, so the bottom edge of the
// photo just stops, hard, at whatever line you draw.
Canvas(Modifier.size(240.dp)) {
    val fadeLine = size.height * 0.7f
    clipRect(bottom = fadeLine) {
        drawImage(photo, dstSize = IntSize(size.width.toInt(), size.height.toInt()))
    }
}
```

Shrinking `fadeLine` gradually doesn't produce a fade, it produces a
smaller hard cutoff. A clip boundary can be anti-aliased (Blending a boundary pixel partway between in-shape and out-of-shape color, based on how much of that one pixel the edge actually covers, so a diagonal or curved line doesn't look stair-stepped.) right at the
one edge it draws, but it can't make the 40px *before* that edge
gradually more transparent, because "gradually transparent" isn't a
clip-stack concept at all. Masking is:

```kotlin
// Layer + mask: draw the photo into its own layer, then composite a
// gradient on top with DstIn. DstIn keeps dst (the photo, already
// rendered) scaled by src's alpha (the gradient), and the gradient's
// alpha runs continuously from 1 to 0, so the photo fades instead of
// cutting off.
Box(
    Modifier
        .size(240.dp)
        .graphicsLayer { compositingStrategy = CompositingStrategy.Offscreen }
        .drawWithContent {
            drawContent()
            drawRect(
                brush = Brush.verticalGradient(
                    0.6f to Color.Black,
                    1f to Color.Transparent,
                ),
                blendMode = BlendMode.DstIn,
            )
        },
) {
    Image(photo, contentDescription = null, modifier = Modifier.fillMaxSize())
}
```

Same visual goal, cut off the bottom of a photo, but the mask version can
express something the clip version structurally cannot: a region that's
partway visible.

*\[Interactive demo: ClipVsMaskDemo — view this post in a browser for the live version.]*

> **The fundamental**
>
> **Clipping** restricts *where* a draw call is allowed to write: a binary
> inside/outside test against a geometric boundary, resolved before any
> painting happens.
>
> **Masking** is an alpha-compositing step, usually `BlendMode.DstIn`/
> `SrcIn` against an already-rendered layer, that multiplies existing
> pixels by a second image's alpha channel. A mask's alpha can vary
> continuously; a clip's answer can only ever be yes or no.
>
> `Modifier.clip(shape)` is the built-in shortcut for the binary case. It
> saves you from managing `clipPath` by hand, but it's still a clip: ask it
> for a soft edge and there's nothing to ask, the shape has no alpha
> channel to grade.
>
> That same asymmetry shows up in what each one takes as input. A clip's
> boundary is always a `Path` (or a `Shape`'s outline, which compiles down
> to one); there's no other way to describe a geometric inside/outside
> test.
>
> A mask's source doesn't have to be. It's just whatever got rendered into
> that layer: a gradient-filled rect, a blurred circle, a photo's own
> pixels. A `Path` is only one of many things you could have drawn there.

## Elsewhere: same fundamental, different framework

* **CSS**: `clip-path` is a hard geometric boundary, binary inside/outside,
  while `mask-image` accepts a gradient or a PNG with partial alpha and
  fades accordingly, because it's reading alpha values, not testing
  membership in a shape.
* **SVG**: `<clipPath>` unions its child shapes into one binary
  inside/outside test. `<mask>` is explicitly graduated by design: white
  pixels in the mask content mean fully visible, black means fully
  hidden, and gray means partially visible, a continuum a `<clipPath>`
  has no way to express.
* **CoreAnimation (iOS)**: `layer.masksToBounds` with `cornerRadius` clips
  to the layer's own geometric bounds, binary, shape-only. Setting
  `layer.mask` to a `CAGradientLayer` instead produces a true alpha fade,
  because `mask` reads the mask layer's alpha channel rather than testing
  a boundary.
* **SwiftUI**: `.clipShape(RoundedRectangle(cornerRadius: 16))` is the
  binary geometric cut, same as everywhere else. `.mask(LinearGradient(
  colors: [.black, .clear], startPoint: .top, endPoint: .bottom))` reads
  the gradient view's alpha instead, the standard SwiftUI trick for
  fading a scroll view's edge, and it's the same DstIn-shaped mechanism
  as the Compose example above, just spelled as a view modifier.
* **Flutter**: `ClipRRect`/`ClipPath`/`ClipOval` push a binary clip onto
  the canvas before painting their child. `ShaderMask` instead applies a
  `Shader` (a `LinearGradient`, say) as an alpha mask over the
  already-painted child via a `BlendMode`, the same DstIn-style
  continuous fade.

## Use cases: which one you actually reach for

* **Rounded avatar or thumbnail**: clip. The edge is a fixed geometric
  shape with nothing to fade, exactly the binary case clip is built for.
  `Modifier.clip(CircleShape)`.
* **Fading the top/bottom edge of a scrollable list** so rows don't look
  chopped off mid-line: mask. The edge needs to go from fully opaque to
  fully transparent over a span of pixels, something only a continuous
  alpha gradient can express, not a boundary test.
* **Knockout text cut into a photo** (the text-shaped hole look): mask,
  via `BlendMode.DstOut`, because you're erasing part of an
  already-painted layer based on another shape's alpha, not restricting
  where a draw call is allowed to land.
* **Cropping a photo to a fixed aspect-ratio frame**: clip. The frame's
  edge is a fixed geometric boundary, there's nothing to fade, the pixels
  outside it just shouldn't exist.
* **Soft vignette around a photo's border**: mask, with a radial gradient
  as the alpha source, the same DstIn mechanism as the fade example
  above, just radial instead of linear.

## Edge cases

* **Clipping away your own shadow.** `clip()` doesn't carve out an
  exception for "content that's meant to bleed." It applies the same
  binary inside/outside test to every draw call nested inside it,
  including a `shadow()`'s own blur, so a shadow nested inside a clip
  gets silently cut off exactly at the boundary it was supposed to spill
  past:

  ```kotlin
  // clip is outside shadow here, so shadow is nested inside the clip
  // scope. The clip stack doesn't know "that draw call was a shadow,"
  // it just sees a draw call outside its geometric bounds and discards it.
  Modifier
      .clip(RoundedCornerShape(16.dp))
      .shadow(8.dp, RoundedCornerShape(16.dp))
  ```

  This isn't a masking problem to fix with `DstIn`, it's a reminder that
  clip is unconditional: anything you don't want flattened against that
  boundary has to be drawn outside the clipped scope entirely, not inside
  it with a bigger radius.

* **Nested clips intersect (Only the area inside both shapes counts, like stacking two stencils: the hole you get is wherever their holes overlap, not either stencil's hole on its own.), they don't override.** Two nested `clipRect`
  (or `clipPath`) scopes don't let the inner one replace the outer one's
  boundary, the clip stack ANDs them together:

  ```kotlin
  // Outer clip keeps only the left 80% of the canvas. Inner clip asks
  // for the right 80%. They overlap in the middle 60%, and that's all
  // that's actually visible, even though the inner clip's own bounds
  // reach further right than the outer clip allows.
  clipRect(right = size.width * 0.8f) {
      clipRect(left = size.width * 0.2f) {
          drawImage(photo, dstSize = IntSize(size.width.toInt(), size.height.toInt()))
      }
  }
  ```

  If you expected the innermost clip to define the final visible area on
  its own, this is the surprise: visibility is always the intersection of
  every clip currently on the stack, never just the most recent one.

## Mental model to actually use

**Clip answers a yes/no question (is this point inside the shape); mask
answers a how-much question (multiply this pixel's alpha by that one).
Reach for clip when the edge really is a hard geometric line, and reach
for a mask the moment any part of that edge needs to be anything other
than fully in or fully out.**


---

Canonical page: https://recomposed.blog/canvas-clip-vs-layer-mask