CKTIS / JavaScript
Canvas 2D: apagar, desenhar e editar píxeis
Distingue as operações de desenho no contexto 2D da leitura e escrita diretas dos píxeis do mapa de bits.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const ctx = canvas.getContext('2d');
ctx.clearRect(x, y, width, height);
ctx.drawImage(image, dx, dy);
ctx.drawImage(image, dx, dy, dw, dh);
ctx.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh);
const snapshot = ctx.getImageData(sx, sy, sw, sh);
const configuredSnapshot = ctx.getImageData(sx, sy, sw, sh, settings);
ctx.putImageData(imageData, dx, dy);
ctx.putImageData(imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);clearRect, drawImage, getImageData e putImageData são métodos de instância do contexto devolvido por canvas.getContext('2d'). Pertencem às APIs Web, não a ECMAScript 2024. clearRect() respeita a transformação e a região de recorte atuais. Coloca os píxeis a preto transparente (preto opaco com alpha: false), sem repor o estado de desenho nem o traçado atual. Usa beginPath() para iniciar um novo traçado.
drawImage() aceita uma fonte CanvasImageSource pronta a usar, como uma imagem ou outro canvas, mas não ImageData. Com 3 argumentos, desenha a fonte inteira no seu tamanho intrínseco; com 5, define o tamanho de destino; com 9, mapeia um retângulo de origem para um de destino. Dimensões negativas estendem o retângulo no sentido oposto sem espelhar a imagem. O desenho respeita a transformação, o recorte e a composição. Se uma imagem ainda estiver a carregar e não puder ser usada, drawImage() não a desenha. Uma imagem totalmente disponível e que possa ser descodificada pode ser desenhada sem chamar primeiro decode() nem precisar de um fotograma já descodificado. Um canvas de origem com uma dimensão nula lança InvalidStateError.
getImageData() lê píxeis do mapa de bits sem aplicar a transformação nem o recorte. Devolve uma cópia ImageData independente: alterar data não muda o canvas. O array guarda valores RGBA por linhas; o primeiro canal do píxel (x, y) na cópia está no índice (y * imageData.width + x) * 4. Fora do mapa de bits, a leitura devolve preto transparente. Valores negativos de sw ou sh estendem o retângulo no sentido oposto; uma dimensão nula lança IndexSizeError.
putImageData() substitui píxeis sem redimensionamento, transformação, recorte do contexto ou mistura. A forma de 7 argumentos seleciona um sub-retângulo em ImageData, não no destino: o píxel (x, y) vai para (dx + x, dy + y). Um buffer desanexado provoca InvalidStateError. A conversão do espaço de cor e a pré-multiplicação alfa podem alterar os valores numa nova leitura, sobretudo em píxeis semitransparentes.
Desenhar um recurso de outra origem sem autorização CORS pode fazer com que o mapa de bits deixe de estar origin-clean. A leitura lança então SecurityError, mesmo após clearRect(). Para recursos de outra origem, usa um pedido CORS com a permissão adequada do servidor. O formato de leitura predefinido rgba-unorm8 usa Uint8ClampedArray; verifica o suporte de opções como display-p3 ou rgba-float16 (Float16Array) nos navegadores de destino.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>Canvas 2D pixel readback</title>
<canvas id="source" width="2" height="1" hidden></canvas>
<canvas id="destination" width="2" height="1" hidden></canvas>
<script>
const source = document.getElementById('source');
const canvas = document.getElementById('destination');
const src = source.getContext('2d');
const ctx = canvas.getContext('2d');
src.fillStyle = '#ff0000';
src.fillRect(0, 0, 2, 1);
ctx.drawImage(source, 0, 0);
ctx.clearRect(0, 0, 1, 1);
const snapshot = ctx.getImageData(0, 0, 2, 1);
console.log(snapshot.data.join(','));
snapshot.data.set([0, 0, 255, 255], 4);
ctx.putImageData(snapshot, -1, 0, 1, 0, 1, 1);
console.log(ctx.getImageData(0, 0, 2, 1).data.join(','));
</script>Resultado
0,0,0,0,255,0,0,255 0,0,255,255,255,0,0,255
A primeira linha mostra o píxel esquerdo apagado e o direito vermelho. O código muda para azul o píxel direito da cópia e escreve só esse píxel com `dx = -1`. A segunda linha mostra o píxel esquerdo azul e o direito ainda vermelho.
Lições relacionadas
- JavaScript · Lição 33 · Avançado · Versão: 4