CKTIS / JavaScript
Canvas 2D: borrar, dibujar y editar píxeles
Distingue las operaciones de dibujo del contexto 2D de la lectura y escritura directas de píxeles del mapa de bits.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
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 y putImageData son métodos de instancia del contexto devuelto por canvas.getContext('2d'). Son API web, no funciones de ECMAScript 2024. clearRect() respeta la transformación y la región de recorte actuales. Pone los píxeles en negro transparente (negro opaco con alpha: false) sin reiniciar el estado de dibujo ni la ruta actual. Usa beginPath() para empezar una ruta nueva.
drawImage() acepta una fuente CanvasImageSource lista para usar, como una imagen u otro lienzo, no ImageData. La forma de 3 argumentos dibuja toda la fuente a su tamaño intrínseco; la de 5 fija el tamaño de destino; la de 9 asigna un rectángulo de origen a otro de destino. Las dimensiones negativas extienden el rectángulo en sentido contrario sin voltear la imagen. El dibujo respeta la transformación, el recorte y la composición. Si una imagen sigue cargándose y aún no se puede usar, drawImage() no la dibuja. Una imagen completamente disponible y que se pueda decodificar puede dibujarse sin llamar antes a decode() ni contar con un fotograma ya decodificado. Un lienzo de origen con una dimensión cero lanza InvalidStateError.
getImageData() lee píxeles del mapa de bits sin aplicar la transformación ni el recorte. Devuelve una copia ImageData independiente: cambiar data no modifica el lienzo. La matriz almacena valores RGBA por filas; el primer canal del píxel (x, y) de la copia está en (y * imageData.width + x) * 4. Fuera del mapa de bits se obtiene negro transparente. Un valor negativo de sw o sh extiende el rectángulo en sentido contrario; una dimensión cero lanza IndexSizeError.
putImageData() sustituye píxeles sin escalado, transformación, recorte del contexto ni mezcla. La forma de 7 argumentos selecciona un subrectángulo dentro de ImageData, no en el destino: el píxel (x, y) se escribe en (dx + x, dy + y). Un búfer separado provoca InvalidStateError. La conversión de espacio de color y la premultiplicación alfa pueden alterar los valores al volver a leerlos, sobre todo en píxeles semitransparentes.
Dibujar un recurso de otro origen sin autorización CORS puede hacer que el mapa de bits pierda el estado origin-clean. La lectura lanza entonces SecurityError, incluso después de clearRect(). Para recursos de otro origen, usa una solicitud CORS con el permiso correspondiente del servidor. El formato de lectura predeterminado rgba-unorm8 usa Uint8ClampedArray; comprueba la compatibilidad con opciones como display-p3 o rgba-float16 (Float16Array) en los navegadores de destino.
Ejemplos
<!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
La primera línea muestra el píxel izquierdo borrado y el derecho rojo. El código cambia a azul el píxel derecho de la copia y escribe solo ese píxel con `dx = -1`. La segunda línea muestra el izquierdo azul y el derecho todavía rojo.
Lecciones relacionadas
- JavaScript · Lección 33 · Avanzado · Versión: 4