new ImageData() — Methode · JavaScript-Referenz

Signatur

new ImageData(width, height, settings) | new ImageData(dataArray, width, height, settings)

Beschreibung

Der Konstruktor ImageData() erzeugt einen rechteckigen Pixelpuffer, der direkt mit CanvasRenderingContext2D.putImageData() auf ein Canvas geschrieben werden kann. Jedes Pixel belegt vier aufeinanderfolgende Bytes in der Reihenfolge Rot, Grün, Blau, Alpha (jeweils 0–255). Die Daten liegen in der Eigenschaft data als Uint8ClampedArray vor.

Es gibt zwei Aufrufformen:

new ImageData(width, height) – legt einen neuen, mit Nullen gefüllten Puffer an (alle Pixel transparent schwarz).
new ImageData(dataArray, width, height) – übernimmt ein bestehendes Uint8ClampedArray. Das Array wird nicht kopiert, das ImageData-Objekt teilt sich den Speicher damit. height ist hier optional und wird aus der Länge abgeleitet.

Der Konstruktor ist praktisch, wenn man Pixel prozedural erzeugt (Farbverläufe, Rauschen, Fraktale), Bilddaten in einem Web Worker berechnet oder Pixelpuffer ohne Canvas-Kontext anlegen möchte. Im Gegensatz zu ctx.createImageData() benötigt er keinen Rendering-Kontext und funktioniert auch in Workern.

Über das optionale Objekt settings lässt sich der Farbraum ("srgb" oder "display-p3") festlegen.

Parameter

Name	Typ	Default	Beschreibung
$dataArray	Uint8ClampedArray		Optional (zweite Aufrufform). Pixeldaten im RGBA-Format. Länge muss ein Vielfaches von `4 * width` sein und darf nicht 0 sein.
$width Pflicht	number		Breite des Bildes in Pixeln (vorzeichenlose Ganzzahl, größer als 0).
$height	number	dataArray.length / (4 * width)	Höhe in Pixeln. In der ersten Form Pflicht; in der zweiten optional, muss aber zu `dataArray.length / (4 * width)` passen.
$settings	{ colorSpace?: "srgb" \| "display-p3" }	{ colorSpace: "srgb" }	Optionales Einstellungsobjekt; `colorSpace` bestimmt den Farbraum der Pixeldaten.

Rückgabewert

Typ

ImageData

Beschreibung

Ein neues ImageData-Objekt mit den Eigenschaften width, height, data und colorSpace.

Beispiele

Leeren Puffer anlegen und Farbverlauf zeichnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const width = 256;
const height = 100;
const img = new ImageData(width, height);

for (let y = 0; y < height; y++) {
  for (let x = 0; x < width; x++) {
    const i = (y * width + x) * 4;
    img.data[i] = x;        // Rot steigt von links nach rechts
    img.data[i + 1] = 0;    // Grün
    img.data[i + 2] = 255 - x; // Blau fällt
    img.data[i + 3] = 255;  // voll deckend
  }
}

ctx.putImageData(img, 0, 0);
console.log(img.width, img.height, img.data.length);

256 100 102400

ImageData aus vorhandenem Uint8ClampedArray

// 2×2 Pixel: rot, grün, blau, weiß
const pixels = new Uint8ClampedArray([
  255, 0, 0, 255,   0, 255, 0, 255,
  0, 0, 255, 255,   255, 255, 255, 255
]);

const img = new ImageData(pixels, 2); // Höhe wird abgeleitet
console.log(img.height);

// Kein Kopieren: Änderungen am Array wirken sich aus
pixels[0] = 0;
console.log(img.data[0]);

2 0

Pixel im Web Worker berechnen (Rauschen)

// worker.js
self.onmessage = ({ data: { width, height } }) => {
  const img = new ImageData(width, height);
  for (let i = 0; i < img.data.length; i += 4) {
    const v = Math.random() * 255;
    img.data[i] = img.data[i + 1] = img.data[i + 2] = v;
    img.data[i + 3] = 255;
  }
  // Puffer übertragen statt kopieren
  self.postMessage(img, [img.data.buffer]);
};

// main.js
// const worker = new Worker('worker.js');
// worker.onmessage = ({ data }) => ctx.putImageData(data, 0, 0);
// worker.postMessage({ width: 320, height: 240 });

Fehlerhafte Maße abfangen

try {
  new ImageData(new Uint8ClampedArray(10), 2);
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Nur Uint8ClampedArray: Ein normales Uint8Array oder Array führt zu einem TypeError. Ggf. mit new Uint8ClampedArray(arr.buffer) umwandeln.
Maße: width oder height gleich 0 oder eine Arraylänge, die kein Vielfaches von 4 * width ist bzw. nicht zu height passt, wirft einen DOMException vom Typ IndexSizeError. Sehr große Maße können einen RangeError auslösen.
Kein Kopieren: Bei der Array-Form teilt sich ImageData den Speicher mit dem übergebenen Array. Wer eine unabhängige Kopie braucht, übergibt pixels.slice().
Nicht vormultipliziertes Alpha: Die Farbwerte sind nicht mit Alpha multipliziert. Beim Rundlauf über putImageData/getImageData können halbtransparente Pixel durch Rundung leicht abweichen.
Performance: Pixelschleifen besser mit flachem Index (i += 4) schreiben; bei großen Bildern ggf. einen Uint32Array-View auf img.data.buffer nutzen (Byte-Reihenfolge beachten, meist Little-Endian → ABGR).
Kompatibilität: Der Konstruktor wird von allen modernen Browsern und in Web Workern unterstützt (nicht im Internet Explorer). Das Argument settings.colorSpace ist neuer und wird nicht überall unterstützt.

Siehe auch

new CSSMathNegate() new Image() new AudioData() new FormData() new ImageCapture()