CanvasRenderingContext2D: putImageData()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die CanvasRenderingContext2D.putImageData()-Methode der Canvas 2D API malt Daten aus dem übergebenen ImageData-Objekt auf die Leinwand. Wird ein "schmutziges" Rechteck angegeben, werden nur die Pixel aus diesem Rechteck gemalt. Diese Methode wird von der Transformationsmatrix der Leinwand nicht beeinflusst.

Hinweis: Bilddaten können von einer Leinwand mithilfe der getImageData()-Methode abgerufen werden.

Weitere Informationen zu putImageData() und der allgemeinen Manipulation von Leinwandinhalten finden Sie im Artikel Pixelmanipulation mit dem Canvas.

Syntax

js
putImageData(imageData, dx, dy)
putImageData(imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight)

Parameter

imageData

Ein ImageData-Objekt, das das Pixelwert-Array enthält.

dx

Horizontale Position (x-Koordinate), an der die Bilddaten auf der Zielleinwand platziert werden sollen.

dy

Vertikale Position (y-Koordinate), an der die Bilddaten auf der Zielleinwand platziert werden sollen.

dirtyX Optional

Horizontale Position (x-Koordinate) der oberen linken Ecke, von der die Bilddaten extrahiert werden. Standardwert ist 0.

dirtyY Optional

Vertikale Position (y-Koordinate) der oberen linken Ecke, von der die Bilddaten extrahiert werden. Standardwert ist 0.

dirtyWidth Optional

Breite des zu malenden Rechtecks. Standardwert ist die Breite der Bilddaten.

dirtyHeight Optional

Höhe des zu malenden Rechtecks. Standardwert ist die Höhe der Bilddaten.

Rückgabewert

Keiner (undefined).

Ausnahmen

NotSupportedError DOMException

Wird ausgelöst, wenn eines der Argumente unendlich ist.

InvalidStateError DOMException

Wird ausgelöst, wenn die Daten des ImageData-Objekts getrennt wurden.

Beispiele

Verständnis von putImageData

Um zu verstehen, was dieser Algorithmus im Hintergrund macht, hier eine Implementierung basierend auf CanvasRenderingContext2D.fillRect().

HTML

html
<canvas id="canvas"></canvas>

JavaScript

js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

function putImageData(
  ctx,
  imageData,
  dx,
  dy,
  dirtyX,
  dirtyY,
  dirtyWidth,
  dirtyHeight,
) {
  const data = imageData.data;
  const height = imageData.height;
  const width = imageData.width;
  dirtyX = dirtyX || 0;
  dirtyY = dirtyY || 0;
  dirtyWidth = dirtyWidth !== undefined ? dirtyWidth : width;
  dirtyHeight = dirtyHeight !== undefined ? dirtyHeight : height;
  const limitBottom = dirtyY + dirtyHeight;
  const limitRight = dirtyX + dirtyWidth;
  for (let y = dirtyY; y < limitBottom; y++) {
    for (let x = dirtyX; x < limitRight; x++) {
      const pos = y * width + x;
      ctx.fillStyle = `rgb(${data[pos * 4 + 0]} ${data[pos * 4 + 1]}
      ${data[pos * 4 + 2]} / ${data[pos * 4 + 3] / 255})`;
      ctx.fillRect(x + dx, y + dy, 1, 1);
    }
  }
}

// Draw content onto the canvas
ctx.fillRect(0, 0, 100, 100);
// Create an ImageData object from it
const imagedata = ctx.getImageData(0, 0, 100, 100);
// use the putImageData function that illustrates how putImageData works
putImageData(ctx, imagedata, 150, 0, 50, 50, 25, 25);

Ergebnis

Datenverlust durch Browser-Optimierung

Warnung: Durch die verlustbehaftete Konvertierung zu und von vorvermultiplizierten Alpha-Farbwerten kann es passieren, dass Pixel, die gerade mit putImageData() gesetzt wurden, in einem entsprechenden getImageData() als unterschiedliche Werte zurückgegeben werden.

JavaScript

js
const canvas = document.createElement("canvas");
canvas.width = 1;
canvas.height = 1;
const context = canvas.getContext("2d");
const imgData = context.getImageData(0, 0, canvas.width, canvas.height);
const pixels = imgData.data;
pixels[0 + 0] = 1;
pixels[0 + 1] = 127;
pixels[0 + 2] = 255;
pixels[0 + 3] = 1;
console.log("before:", pixels);
context.putImageData(imgData, 0, 0);
const imgData2 = context.getImageData(0, 0, canvas.width, canvas.height);
const pixels2 = imgData2.data;
console.log("after:", pixels2);

Die Ausgabe könnte folgendermaßen aussehen:

before: Uint8ClampedArray(4) [ 1, 127, 255, 1 ]
after: Uint8ClampedArray(4) [ 255, 255, 255, 1 ]

Spezifikationen

Specification
HTML Standard
# dom-context-2d-putimagedata-dev

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch