CanvasRenderingContext2D.createImageData() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.createImageData(width, height, settings) | createImageData(imagedata)

Beschreibung

Die Methode createImageData() erzeugt einen leeren Pixelpuffer vom Typ ImageData. Seine Eigenschaft data ist ein Uint8ClampedArray mit width × height × 4 Einträgen, jeweils ein Byte für Rot, Grün, Blau und Alpha. Anfangs sind alle Werte 0, das Bild ist also vollständig transparent.

Es gibt zwei Aufrufvarianten:

Mit Breite und Höhe: Das Objekt bekommt genau diese Maße.
Mit einem vorhandenen ImageData-Objekt: Nur dessen Maße werden übernommen. Die Pixeldaten werden nicht kopiert, das neue Objekt ist leer.

Die Methode eignet sich, wenn du Pixel selbst berechnest, zum Beispiel für Rauschen, Farbverläufe, Fraktale, Bildfilter oder das Ergebnis einer Faltung. Mit putImageData() überträgst du das Ergebnis danach auf den Canvas. Um vorhandene Canvas-Inhalte auszulesen, verwendest du dagegen getImageData().

Das Objekt hängt nicht am Kontext. Du kannst es also mehrfach wiederverwenden. Gleichwertig ist der Konstruktor new ImageData(width, height), der auch ohne Canvas-Kontext funktioniert, etwa in Web Workern.

Parameter

Name	Typ	Default	Beschreibung
$width Pflicht	number		Breite des neuen `ImageData`-Objekts in Pixeln. Negative Werte werden als Betrag behandelt, `0` löst einen `IndexSizeError` aus.
$height Pflicht	number		Höhe in Pixeln. Es gelten dieselben Regeln wie bei `width`.
$settings	{ colorSpace?: 'srgb' \| 'display-p3' }	{ colorSpace: 'srgb' }	Optionale Einstellungen. Mit `colorSpace` legst du den Farbraum der Pixeldaten fest.
$imagedata	ImageData		Alternative Aufrufvariante: ein vorhandenes `ImageData`-Objekt, dessen `width` und `height` übernommen werden. Die Pixeldaten werden nicht kopiert.

Rückgabewert

Typ

ImageData

Beschreibung

Ein neues ImageData-Objekt mit den angegebenen Maßen. Alle Pixel sind transparentes Schwarz.

Beispiele

Leeres ImageData erzeugen und untersuchen

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

const img = ctx.createImageData(100, 50);
console.log(img.width, img.height);   // Maße
console.log(img.data.length);         // 100 * 50 * 4
console.log(img.data[0], img.data[3]); // Alle Werte sind 0

100 50 20000 0 0

Zufallsrauschen pixelweise zeichnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const { width, height } = canvas;

const img = ctx.createImageData(width, height);
const px = img.data;

for (let i = 0; i < px.length; i += 4) {
  const v = Math.random() * 255 | 0;
  px[i] = v;       // Rot
  px[i + 1] = v;   // Grün
  px[i + 2] = v;   // Blau
  px[i + 3] = 255; // Alpha: voll deckend
}

ctx.putImageData(img, 0, 0);

Graustufenfilter mit gleich großem Zielpuffer

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

const src = ctx.getImageData(0, 0, canvas.width, canvas.height);
// Übernimmt nur die Maße, die Pixel bleiben leer
const dst = ctx.createImageData(src);

for (let i = 0; i < src.data.length; i += 4) {
  const [r, g, b, a] = src.data.subarray(i, i + 4);
  const grau = 0.299 * r + 0.587 * g + 0.114 * b;
  dst.data[i] = dst.data[i + 1] = dst.data[i + 2] = grau;
  dst.data[i + 3] = a;
}

ctx.putImageData(dst, 0, 0);

Farbverlauf mit Koordinatenberechnung

const ctx = document.querySelector('canvas').getContext('2d');
const w = 256, h = 64;
const img = ctx.createImageData(w, h);

for (let y = 0; y < h; y++) {
  for (let x = 0; x < w; x++) {
    const i = (y * w + x) * 4; // Index des Pixels (x, y)
    img.data[i] = x;           // Rot steigt nach rechts an
    img.data[i + 2] = 255 - x; // Blau nimmt ab
    img.data[i + 3] = 255;
  }
}

ctx.putImageData(img, 10, 10);

// Wichtig · Fallstricke

Keine Kopie der Pixel: createImageData(vorhandenesImageData) übernimmt nur die Maße. Eine echte Kopie erzeugst du mit new ImageData(new Uint8ClampedArray(src.data), src.width).
Transparent statt schwarz: Wenn du nur RGB setzt und den Alphawert auf 0 lässt, bleibt das Ergebnis unsichtbar. Setze deshalb data[i + 3] = 255.
putImageData ignoriert den Zeichenzustand: Transformationen, globalAlpha, globalCompositeOperation und Clipping-Bereiche wirken nicht. Die Pixel werden 1:1 übernommen, ohne Alpha-Überblendung.
Fehler: Ist width oder height gleich 0, wird ein IndexSizeError ausgelöst. Sehr große Maße können einen RangeError auslösen, weil der Speicher nicht reicht (4 Byte pro Pixel).
Performance: Lege den Puffer in Animationsschleifen einmal an und verwende ihn weiter, statt ihn in jedem Frame neu zu erzeugen. Für schnelle Schreibzugriffe kannst du über new Uint32Array(img.data.buffer) ganze Pixel auf einmal setzen. Beachte dabei die Byte-Reihenfolge (auf den meisten Systemen Little-Endian, also ABGR).
Hohe Pixeldichte: Die Maße gelten in Gerätepixeln des Canvas-Puffers, nicht in CSS-Pixeln. Rechne devicePixelRatio gegebenenfalls selbst ein.
Kompatibilität: Die Methode wird von allen Browsern unterstützt, auch von OffscreenCanvasRenderingContext2D. Der Parameter settings mit colorSpace: 'display-p3' ist neuer und wird noch nicht überall unterstützt.

Siehe auch

ImageData CanvasRenderingContext2D.getImageData() CanvasRenderingContext2D.putImageData() CanvasRenderingContext2D Uint8ClampedArray OffscreenCanvas