ImageBitmapRenderingContext — Schnittstelle · JavaScript-Referenz

Signatur

interface ImageBitmapRenderingContext

Beschreibung

ImageBitmapRenderingContext ist ein sehr schlanker Rendering-Kontext, den man mit canvas.getContext("bitmaprenderer") erhält. Er kann nicht zeichnen und bietet nur eine Methode: transferFromImageBitmap(bitmap). Diese überträgt den Besitz eines ImageBitmap an das Canvas. Das Bild wird also nicht Pixel für Pixel kopiert, sondern übernommen. Deshalb ist der Aufruf deutlich schneller als drawImage() auf einem 2D-Kontext.

Typischerweise nutzt man den Kontext zusammen mit OffscreenCanvas und Web Workern. Ein Worker rendert in ein OffscreenCanvas, erzeugt mit transferToImageBitmap() ein Bild und schickt es als übertragbares Objekt (Transferable) an den Haupt-Thread. Dort wird es mit transferFromImageBitmap() fast ohne Aufwand angezeigt. Das eignet sich für Doppelpufferung (Double Buffering), Bildbearbeitung im Hintergrund und flüssige Animationen, ohne die Oberfläche zu blockieren.

Eigenschaften und Methoden:

canvas (nur lesbar): Verweis auf das zugehörige HTMLCanvasElement oder OffscreenCanvas.
transferFromImageBitmap(bitmap): Zeigt das übergebene ImageBitmap an. Übergibt man null, wird das Canvas geleert, also vollständig transparent schwarz.

Parameter

Name	Typ	Default	Beschreibung
$contextType Pflicht	"bitmaprenderer"		Wird an `canvas.getContext()` übergeben, um diesen Kontext zu erzeugen.
$contextAttributes.alpha	boolean	true	Mit `false` wird das Canvas als undurchsichtig behandelt. Transparente Bereiche erscheinen dann schwarz, und der Browser kann dadurch schneller zusammensetzen (Compositing).
$bitmap Pflicht	ImageBitmap \| null		Parameter von `transferFromImageBitmap()`: Das anzuzeigende Bild. Nach dem Aufruf ist es detached, also unbrauchbar (Breite und Höhe sind dann 0). Mit `null` wird das Canvas geleert.

Beispiele

Kontext erzeugen und ImageBitmap anzeigen

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

// Bild laden und als ImageBitmap dekodieren
const response = await fetch('/bilder/foto.jpg');
const blob = await response.blob();
const bitmap = await createImageBitmap(blob);

canvas.width = bitmap.width;
canvas.height = bitmap.height;
ctx.transferFromImageBitmap(bitmap);

console.log(bitmap.width); // Bitmap wurde übertragen und ist jetzt detached

Doppelpufferung mit OffscreenCanvas

const sichtbar = document.querySelector('#sichtbar');
const ctx = sichtbar.getContext('bitmaprenderer');
const offscreen = new OffscreenCanvas(300, 150);
const g = offscreen.getContext('2d');

let x = 0;
const frame = () => {
  g.clearRect(0, 0, 300, 150);
  g.fillStyle = 'tomato';
  g.fillRect(x, 50, 50, 50);
  x = (x + 2) % 300;
  // fertigen Frame ohne Kopie übergeben
  ctx.transferFromImageBitmap(offscreen.transferToImageBitmap());
  requestAnimationFrame(frame);
};
requestAnimationFrame(frame);

Rendering im Web Worker, Anzeige im Haupt-Thread

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

worker.onmessage = ({ data }) => {
  ctx.transferFromImageBitmap(data.bitmap);
};
worker.postMessage({ width: canvas.width, height: canvas.height });

// render-worker.js
self.onmessage = ({ data }) => {
  const off = new OffscreenCanvas(data.width, data.height);
  const g = off.getContext('2d');
  g.fillStyle = 'steelblue';
  g.fillRect(0, 0, data.width, data.height);
  const bitmap = off.transferToImageBitmap();
  // als Transferable übergeben: keine Kopie
  self.postMessage({ bitmap }, [bitmap]);
};

Canvas leeren

const ctx = document.querySelector('canvas').getContext('bitmaprenderer');
ctx.transferFromImageBitmap(null); // Canvas wird transparent schwarz
console.log(ctx.canvas.tagName);

CANVAS

// Wichtig · Fallstricke

Ein Kontext pro Canvas: Hat das Canvas schon einen "2d"- oder "webgl"-Kontext, gibt getContext("bitmaprenderer") null zurück, und umgekehrt genauso.
Bitmap wird verbraucht: Nach transferFromImageBitmap() ist das ImageBitmap detached. Wer es mehrfach anzeigen will, muss es vorher klonen (z. B. mit createImageBitmap(bitmap)). Ist die Bitmap schon detached, wirft der Aufruf einen InvalidStateError.
Größe: Das Bild wird nicht automatisch an das Canvas angepasst. Die Anzeige skaliert anhand von width/height des Canvas. Für scharfe Darstellung sollte man diese Werte auf die Maße der Bitmap setzen.
Keine Zeichenmethoden: Pfade, Text oder Filter gibt es hier nicht. Gezeichnet wird vorher in einem OffscreenCanvas oder einem anderen Kontext.
Kompatibilität: Wird in allen modernen Browsern unterstützt. OffscreenCanvas gibt es in Safari erst ab Version 16.4. Für ältere Safari-Versionen braucht man eine Ausweichlösung über drawImage().
Canvas-Inhalte aus fremden Quellen ohne CORS machen das Canvas tainted. Das gilt auch hier: toDataURL() oder toBlob() schlagen danach fehl.

Siehe auch

WebGL2RenderingContext WebGLRenderingContext CanvasRenderingContext2D PaintRenderingContext2D BaseAudioContext