OffscreenCanvas: transferToImageBitmap() Methode

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die OffscreenCanvas.transferToImageBitmap()-Methode erzeugt ein ImageBitmap-Objekt aus dem zuletzt gerenderten Bild des OffscreenCanvas. Das OffscreenCanvas reserviert ein neues Bild für seine nachfolgende Darstellung.

Syntax

js
transferToImageBitmap()

Parameter

Keine.

Rückgabewert

Ein neu allokiertes ImageBitmap.

Dieses ImageBitmap bezieht sich auf eine potenziell große Grafikressource, und um sicherzustellen, dass Ihre Webanwendung robust bleibt, ist es wichtig, nicht zu viele dieser Ressourcen gleichzeitig zu allokieren. Aus diesem Grund ist es wichtig, sicherzustellen, dass das ImageBitmap entweder konsumiert oder geschlossen wird.

Wie in den Beispielen zum OffscreenCanvas beschrieben, wird das Übergeben dieses ImageBitmap an ImageBitmapRenderingContext.transferFromImageBitmap() das ImageBitmap-Objekt konsumiert; es bezieht sich nicht mehr auf die zugrunde liegende Grafikressource und kann nicht an andere Web-APIs übergeben werden.

Wenn Ihr Ziel darin besteht, das ImageBitmap an andere Web-APIs zu übergeben, die es nicht konsumieren - zum Beispiel CanvasRenderingContext2D.drawImage() - dann sollten Sie es schließen, wenn Sie damit fertig sind, indem Sie ImageBitmap.close() aufrufen. Lassen Sie nicht einfach die JavaScript-Referenz auf das ImageBitmap fallen; dadurch bleibt die Grafikressource erhalten, bis der Müllsammler das nächste Mal läuft.

Wenn Sie transferToImageBitmap() aufrufen und nicht beabsichtigen, es an ImageBitmapRenderingContext.transferFromImageBitmap() zu übergeben, überlegen Sie, ob Sie transferToImageBitmap() überhaupt aufrufen müssen. Viele Web-APIs, die ImageBitmap akzeptieren, akzeptieren auch OffscreenCanvas als Argument.

Ausnahmen

InvalidStateError DOMException

Wirft eine Ausnahme, wenn:

  • die Leinwand in einen anderen Kontextbereich, wie einen Worker, übertragen wurde
  • der Leinwandkontextmodus nicht durch Aufruf von OffscreenCanvas.getContext() gesetzt wurde.

Beispiele

js
const offscreen = new OffscreenCanvas(256, 256);
const gl = offscreen.getContext("webgl");

// Perform some drawing using the gl context

offscreen.transferToImageBitmap();
// ImageBitmap { width: 256, height: 256 }

// Either:
// Pass this `ImageBitmap` to `ImageBitmapRenderingContext.transferFromImageBitmap`
// or:
// Use the `ImageBitmap` with other web APIs, and call `ImageBitmap.close()`!

Spezifikationen

Specification
HTML Standard
# dom-offscreencanvas-transfertoimagebitmap-dev

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch