CKTIS / JavaScript
Canvas 2D: transformações, estado de desenho, recorte e retângulos
Distingue o estado de desenho do caminho atual e do mapa de bits para limitar o recorte a uma etapa do desenho e apagar apenas os píxeis pretendidos.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
ctx.setTransform(a, b, c, d, e, f)
ctx.setTransform()
ctx.setTransform(matrix2D)
ctx.save()
ctx.restore()
ctx.beginPath()
ctx.rect(x, y, width, height)
ctx.clip()
ctx.clip(fillRule)
ctx.clip(path)
ctx.clip(path, fillRule)
ctx.clearRect(x, y, width, height)
ctx.fillRect(x, y, width, height)
ctx.strokeRect(x, y, width, height)Estes métodos pertencem à interface Web CanvasRenderingContext2D, não ao ECMAScript 2024. O suporte varia consoante o ambiente de execução. setTransform(a, b, c, d, e, f) substitui a matriz, em vez de a multiplicar: (x, y) passa a (a*x + c*y + e, b*x + d*y + f). Também aceita um objeto DOMMatrix2DInit: por omissão, a e d valem 1 e os restantes coeficientes valem 0. Assim, uma chamada sem argumentos define a matriz identidade. Valores incompatíveis em chaves sinónimas, como a e m11, lançam TypeError. Na forma com seis números, a matriz não muda se algum argumento for infinito ou NaN.
save() coloca na pilha uma cópia do estado de desenho, que inclui a transformação, a região de recorte e os estilos. restore() retira e repõe o último estado guardado; se a pilha estiver vazia, não faz nada. Nem o caminho atual nem os píxeis são guardados. beginPath() esvazia o caminho sem alterar o recorte nem o mapa de bits. rect(x, y, width, height) acrescenta um subcaminho retangular fechado sem pintar píxeis. A transformação aplica-se à geometria desse caminho à medida que este é construído.
clip() substitui a região de recorte pela sua interseção com o interior do caminho atual ou do Path2D fornecido. No caso de Path2D, a transformação aplica-se na chamada a clip(), sem modificar o objeto. A regra de preenchimento opcional 'nonzero' (por omissão) verifica se a contagem com sinal das travessias é diferente de zero; 'evenodd' verifica se o número de travessias é ímpar. clip() não pinta nada e as chamadas sucessivas não podem alargar a região. Guarda o estado antes de recortar e repõe-no depois de desenhar: definir a matriz identidade não remove o recorte.
fillRect() preenche com fillStyle, strokeRect() desenha o contorno com strokeStyle e as definições de linha, e clearRect() apaga para preto transparente (preto opaco com alpha: false), ignorando sombras, alfa global e composição. Os três atuam diretamente no mapa de bits, respeitam a transformação e o recorte e deixam o caminho inalterado. Por isso, fillRect() não fornece geometria a clip(). clearRect() não remove as restrições de leitura de um mapa de bits contaminado por dados de outra origem: getImageData() continua a lançar SecurityError.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>Canvas 2D clipping</title>
<canvas id="canvas" width="20" height="12"></canvas>
<script>
(() => {
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d', { alpha: true });
if (!ctx) throw new Error('Canvas 2D unavailable');
ctx.fillRect(0, 0, 12, 12);
ctx.save();
try {
ctx.setTransform(1, 0, 0, 1, 4, 2);
ctx.beginPath();
ctx.rect(0, 0, 8, 8);
ctx.clip();
ctx.clearRect(-2, 2, 6, 4);
} finally {
ctx.restore();
}
ctx.lineWidth = 2;
ctx.strokeRect(14, 2, 4, 8);
const alphaAt = (x, y) => ctx.getImageData(x, y, 1, 1).data[3];
console.log([3, 5, 9, 14, 16].map(x => alphaAt(x, 5)).join(', '));
})();
</script>Resultado
255, 0, 255, 255, 0
Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta a consola de desenvolvimento. Os cinco valores alfa mostram, por ordem: o preenchimento protegido pelo recorte, um píxel apagado, o preenchimento intacto, o contorno desenhado após repor o estado e o interior transparente desse contorno.
Lições relacionadas
- JavaScript · Lição 12 · Avançado · Versão: 4
Fontes
- HTML Standard — The canvas state
- HTML Standard — Transformations
- HTML Standard — Drawing rectangles to the bitmap
- HTML Standard — Drawing paths to the canvas
- HTML Standard — The canvas settings
- CanvasRenderingContext2D: setTransform() method
- CanvasRenderingContext2D: rect() method
- CanvasRenderingContext2D: getImageData() method