ImageBitmapRenderingContext.transferFromImageBitmap() — Methode · JavaScript-Referenz

Signatur

ImageBitmapRenderingContext.prototype.transferFromImageBitmap(bitmap)

Beschreibung

transferFromImageBitmap() ist die einzige Methode des ImageBitmapRenderingContext. Den Kontext erhalten Sie über canvas.getContext("bitmaprenderer"). Die Methode übergibt die Pixeldaten eines ImageBitmap direkt an das Canvas. Es wird nichts gezeichnet und nichts kopiert, der Browser tauscht nur den Inhalt des Canvas aus. Deshalb ist dieser Weg meist schneller und braucht weniger Speicher als drawImage() auf einem 2D-Kontext.

Gedacht ist die Methode vor allem für Bilder, die an anderer Stelle berechnet wurden, zum Beispiel in einem Web Worker auf einem OffscreenCanvas. Mit OffscreenCanvas.transferToImageBitmap() erzeugen Sie dort ein Bitmap, schicken es per postMessage() als übertragbares Objekt (Transferable) an den Hauptthread und zeigen es mit transferFromImageBitmap() an. Auch Bilder, die mit createImageBitmap() dekodiert wurden, lassen sich so sehr effizient darstellen.

Nach dem Aufruf ist das übergebene ImageBitmap abgekoppelt („detached“). Seine width und height sind dann 0, und Sie können es nicht erneut verwenden. Übergeben Sie null, wird das Canvas geleert und zeigt ein transparentes schwarzes Bild in der aktuellen Canvas-Größe.

Parameter

Name	Typ	Default	Beschreibung
$bitmap Pflicht	ImageBitmap \| null		Das anzuzeigende `ImageBitmap`. Der Kontext wird sein Eigentümer, das Objekt ist danach abgekoppelt. Bei `null` wird der Canvas-Inhalt auf transparentes Schwarz zurückgesetzt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Bild dekodieren und ohne Kopie anzeigen

const canvas = document.querySelector('#preview');
const ctx = canvas.getContext('bitmaprenderer');

const showImage = async (url) => {
  const response = await fetch(url);
  const blob = await response.blob();
  const bitmap = await createImageBitmap(blob);
  canvas.width = bitmap.width;
  canvas.height = bitmap.height;
  ctx.transferFromImageBitmap(bitmap);
  console.log('Nach Transfer:', bitmap.width, bitmap.height);
};

showImage('/img/foto.jpg');

Nach Transfer: 0 0

Im Worker rendern, im Hauptthread anzeigen

// worker.js
const offscreen = new OffscreenCanvas(300, 150);
const octx = offscreen.getContext('2d');

self.onmessage = ({ data }) => {
  octx.fillStyle = data.color;
  octx.fillRect(0, 0, 300, 150);
  const bitmap = offscreen.transferToImageBitmap();
  self.postMessage(bitmap, [bitmap]); // als Transferable, ohne Kopie
};

// main.js
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('bitmaprenderer');
const worker = new Worker('worker.js');

worker.onmessage = ({ data: bitmap }) => {
  ctx.transferFromImageBitmap(bitmap);
};
worker.postMessage({ color: 'tomato' });

Canvas mit null leeren

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

const bitmap = await createImageBitmap(new ImageData(10, 10));
ctx.transferFromImageBitmap(bitmap);

// Inhalt wieder entfernen, danach ist das Canvas transparent
ctx.transferFromImageBitmap(null);
console.log('Canvas geleert');

Canvas geleert

// Wichtig · Fallstricke

Abgekoppeltes Bitmap: Wenn Sie dasselbe ImageBitmap ein zweites Mal übergeben, wird ein InvalidStateError (DOMException) ausgelöst. Brauchen Sie das Bild mehrfach, erzeugen Sie es mit createImageBitmap() neu.
Größe: Das Canvas passt sich nicht automatisch an das Bitmap an. Weichen die Maße ab, skaliert der Browser das Bild auf die Anzeigefläche, gesteuert über CSS, z. B. mit object-fit. Setzen Sie canvas.width und canvas.height passend, bevor Sie das Bild übertragen.
Ein Kontext pro Canvas: Hat ein Canvas bereits einen 2d- oder webgl-Kontext, liefert getContext('bitmaprenderer') null.
Speicher: Das Canvas übernimmt das Bitmap. Ein vorher angezeigtes Bitmap wird freigegeben, ein zusätzliches close() ist nicht nötig.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch von OffscreenCanvas (ab Safari 16.4 vollständig). In sehr alten Firefox-Versionen hieß die Methode transferImageBitmap().

Siehe auch

WebGLRenderingContext.generateMipmap() OffscreenCanvas.transferToImageBitmap() CanvasRenderingContext2D.createImageData() CanvasRenderingContext2D.getImageData() WebGL2RenderingContext.isTransformFeedback()