Recomposed
Canvas

Fundamentos de Clipping: Canvas Clip Stack vs. Layer + Outline Mask

Oct 18, 2026 · 6 min read

Fundamentos de Clipping: Canvas Clip Stack vs. Layer + Outline Mask

A intuição

É tentador tratar clipping e masking como o mesmo movimento com duas APIs diferentes: ambos "cortam a parte deste conteúdo que eu não quero". Esse é o resultado certo para o caso simples, e o modelo mental errado no momento em que a borda fica mais interessante do que uma linha dura.

  • Um clip é um teste sim/não: para cada pixel que uma chamada de desenho tenta tocar, a clip stack pergunta "esse ponto está dentro da forma", e a resposta é binária. Não existe um pixel que esteja 60% clipado.
  • Uma mask é uma multiplicação de alpha: ela pega o que já foi renderizado e escala seu alpha pelo alpha de uma segunda imagem, pixel por pixel. Essa segunda imagem pode carregar qualquer valor de alpha entre 0 e 1, um gradiente, um blur, a luminância da própria foto, não apenas "forma" ou "não forma".
  • Clipping é resolvido antes de uma chamada de desenho pintar qualquer coisa, como uma restrição de onde ela tem permissão para escrever. Masking é resolvido como um blend, contra conteúdo que já foi totalmente pintado.

Esses dois mecanismos acabam produzindo pixels idênticos em um caso específico: uma forma opaca com uma borda dura. Essa sobreposição é exatamente o motivo pelo qual eles são tratados como intercambiáveis, até o momento em que você precisa de uma borda suave e descobre que um deles estruturalmente não consegue te dar isso.

Exemplo concreto: esmaecendo a borda de uma foto

Primeiro você recorre ao clipPath, porque é a ferramenta óbvia para "cortar isso em uma forma":

// 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()))
    }
}

Diminuir fadeLine gradualmente não produz um fade, produz um corte duro menor. Uma borda de clip pode ter exatamente na única borda que ela desenha, mas não pode fazer os 40px antes dessa borda ficarem gradualmente mais transparentes, porque "gradualmente transparente" não é um conceito de clip stack. Masking é:

// 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())
}

Mesmo objetivo visual, cortar a parte inferior de uma foto, mas a versão com mask consegue expressar algo que a versão com clip estruturalmente não consegue: uma região parcialmente visível.

Drag the line. Everything past it is just gone, no partial values. Clip mode: the boundary is a hard yes or no test, nothing past the line is visible, with no gradual fade.

O fundamento

Clipping restringe onde uma chamada de desenho tem permissão para escrever: um teste binário dentro/fora contra um limite geométrico, resolvido antes de qualquer pintura acontecer.

Masking é uma etapa de alpha-compositing, geralmente BlendMode.DstIn/SrcIn contra uma layer já renderizada, que multiplica os pixels existentes pelo canal alpha de uma segunda imagem. O alpha de uma mask pode variar continuamente; a resposta de um clip só pode ser sim ou não.

Modifier.clip(shape) é o atalho embutido para o caso binário. Ele te livra de gerenciar clipPath manualmente, mas ainda é um clip: peça a ele uma borda suave e não há nada a pedir, a forma não tem canal alpha para graduar.

Essa mesma assimetria aparece no que cada um recebe como entrada. A borda de um clip é sempre um Path (ou o outline de uma Shape, que se compila para um); não há outra forma de descrever um teste geométrico dentro/fora.

A fonte de uma mask não precisa ser isso. É apenas o que foi renderizado naquela layer: um rect preenchido com gradiente, um círculo com blur, os próprios pixels de uma foto. Um Path é apenas uma das muitas coisas que você poderia ter desenhado ali.

Em outros lugares: mesmo fundamento, framework diferente

  • CSS: clip-path é um limite geométrico duro, dentro/fora binário, enquanto mask-image aceita um gradiente ou um PNG com alpha parcial e esmaece de acordo, porque está lendo valores de alpha, não testando pertencimento a uma forma.
  • SVG: <clipPath> une suas formas filhas em um único teste binário dentro/fora. <mask> é explicitamente graduado por design: pixels brancos no conteúdo da mask significam totalmente visível, preto significa totalmente oculto, e cinza significa parcialmente visível, um continuum que um <clipPath> não tem como expressar.
  • CoreAnimation (iOS): layer.masksToBounds com cornerRadius recorta para os limites geométricos da própria layer, binário, apenas forma. Definir layer.mask para um CAGradientLayer em vez disso produz um verdadeiro fade de alpha, porque mask lê o canal alpha da layer de mask em vez de testar um limite.
  • SwiftUI: .clipShape(RoundedRectangle(cornerRadius: 16)) é o corte geométrico binário, igual em todo lugar. .mask(LinearGradient( colors: [.black, .clear], startPoint: .top, endPoint: .bottom)) lê o alpha da view de gradiente em vez disso, o truque padrão do SwiftUI para esmaecer a borda de uma scroll view, e é o mesmo mecanismo em formato DstIn do exemplo em Compose acima, apenas escrito como um view modifier.
  • Flutter: ClipRRect/ClipPath/ClipOval empurram um clip binário para o canvas antes de pintar seu filho. ShaderMask em vez disso aplica um Shader (um LinearGradient, por exemplo) como uma mask de alpha sobre o filho já pintado via um BlendMode, o mesmo fade contínuo no estilo DstIn.

Casos de uso: para qual deles você realmente recorre

  • Avatar ou thumbnail arredondado: clip. A borda é uma forma geométrica fixa sem nada para esmaecer, exatamente o caso binário para o qual o clip foi construído. Modifier.clip(CircleShape).
  • Esmaecer a borda superior/inferior de uma lista rolável para que as linhas não pareçam cortadas no meio: mask. A borda precisa ir de totalmente opaca para totalmente transparente ao longo de uma faixa de pixels, algo que só um gradiente de alpha contínuo consegue expressar, não um teste de limite.
  • Texto em negativo recortado em uma foto (o efeito de buraco em forma de texto): mask, via BlendMode.DstOut, porque você está apagando parte de uma layer já pintada com base no alpha de outra forma, não restringindo onde uma chamada de desenho tem permissão para aterrissar.
  • Cortar uma foto para um frame de proporção fixa: clip. A borda do frame é um limite geométrico fixo, não há nada para esmaecer, os pixels fora dele simplesmente não deveriam existir.
  • Vinheta suave na borda de uma foto: mask, com um gradiente radial como fonte de alpha, o mesmo mecanismo DstIn do exemplo de fade acima, apenas radial em vez de linear.

Casos extremos

  • Recortando a própria sombra. clip() não abre uma exceção para "conteúdo que deveria sangrar para fora". Ele aplica o mesmo teste binário dentro/fora a toda chamada de desenho aninhada dentro dele, incluindo o blur de um shadow(), então uma sombra aninhada dentro de um clip é silenciosamente cortada exatamente no limite que deveria ultrapassar:

    // clip está fora de shadow aqui, então shadow fica aninhado dentro do
    // escopo do clip. A clip stack não sabe "essa chamada de desenho era
    // uma sombra", ela só vê uma chamada de desenho fora dos seus limites
    // geométricos e a descarta.
    Modifier
        .clip(RoundedCornerShape(16.dp))
        .shadow(8.dp, RoundedCornerShape(16.dp))

    Isso não é um problema de masking para corrigir com DstIn, é um lembrete de que clip é incondicional: qualquer coisa que você não queira achatada contra aquele limite tem que ser desenhada inteiramente fora do escopo recortado, não dentro dele com um raio maior.

  • Clips aninhados se , eles não se sobrescrevem. Dois escopos clipRect (ou clipPath) aninhados não permitem que o interno substitua o limite do externo, a clip stack os combina com um AND:

    // O clip externo mantém apenas os 80% da esquerda do canvas. O clip
    // interno pede os 80% da direita. Eles se sobrepõem nos 60% do meio,
    // e é só isso que está realmente visível, mesmo que os próprios
    // limites do clip interno alcancem mais à direita do que o clip
    // externo permite.
    clipRect(right = size.width * 0.8f) {
        clipRect(left = size.width * 0.2f) {
            drawImage(photo, dstSize = IntSize(size.width.toInt(), size.height.toInt()))
        }
    }

    Se você esperava que o clip mais interno definisse a área visível final por conta própria, essa é a surpresa: a visibilidade é sempre a interseção de todos os clips atualmente na pilha, nunca apenas o mais recente.

Modelo mental para realmente usar

Clip responde a uma pergunta sim/não (esse ponto está dentro da forma); mask responde a uma pergunta de quanto (multiplique o alpha deste pixel por aquele outro). Recorra ao clip quando a borda realmente for uma linha geométrica dura, e recorra a uma mask no momento em que qualquer parte dessa borda precisar ser algo diferente de totalmente dentro ou totalmente fora.

Keep reading

Related reads

Receba novos posts no seu e-mail