OffscreenCanvas: transferToImageBitmap() Methode
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit März 2023 browserübergreifend verfügbar.
Hinweis: Diese Funktion ist in Web Workers verfügbar.
Die transferToImageBitmap() Methode des OffscreenCanvas Schnittstelle erstellt ein ImageBitmap Objekt aus dem zuletzt gerenderten Bild des OffscreenCanvas. Das Bild im OffscreenCanvas wird durch ein neues leeres Bild für die nachfolgende Darstellung ersetzt.
Wenn Sie nur den aktuellen Inhalt des OffscreenCanvas in ein anderes Canvas kopieren müssen, verwenden Sie die CanvasRenderingContext2D.drawImage() Methode des Canvas-Kontextes mit dem OffscreenCanvas als Eingabe.
Syntax
transferToImageBitmap()
Parameter
Keine.
Rückgabewert
Ein neu zugewiesenes ImageBitmap.
Ausnahmen
InvalidStateErrorDOMException-
Wird ausgelöst, wenn:
- das Canvas in einen anderen Kontextbereich, wie z.B. einen Worker, übertragen wurde
- der Canvas-Kontextmodus nicht durch Aufrufen von
OffscreenCanvas.getContext()gesetzt wurde.
Beschreibung
Dieses ImageBitmap referenziert eine potenziell große Grafikressource, und um sicherzustellen, dass Ihre Webanwendung robust bleibt, ist es wichtig, zu vermeiden, dass zu viele dieser Ressourcen gleichzeitig zugewiesen werden. Aus diesem Grund ist es wichtig sicherzustellen, dass das ImageBitmap entweder verbraucht oder geschlossen wird.
Wie in den OffscreenCanvas Beispielen beschrieben, konsumiert das Übergeben dieses ImageBitmap an ImageBitmapRenderingContext.transferFromImageBitmap() das ImageBitmap Objekt; es referenziert nicht mehr die zugrundeliegende Grafikressource und kann nicht an andere Web-APIs weitergegeben werden.
Wenn Ihr Ziel darin besteht, das ImageBitmap an andere Web-APIs weiterzugeben, die es nicht konsumieren - zum Beispiel CanvasRenderingContext2D.drawImage() - sollten Sie es schließen, wenn Sie damit fertig sind, indem Sie ImageBitmap.close() aufrufen. Lassen Sie nicht einfach den JavaScript-Verweis auf das ImageBitmap fallen; dies würde die Grafikressource bis zum nächsten Lauf des Garbage Collectors am Leben halten.
Wenn Sie transferToImageBitmap() aufrufen und nicht beabsichtigen, es an ImageBitmapRenderingContext.transferFromImageBitmap() weiterzugeben, überlegen Sie, ob Sie transferToImageBitmap() überhaupt aufrufen müssen. Viele Web-APIs, die ImageBitmap akzeptieren, akzeptieren auch OffscreenCanvas als Argument, einschließlich CanvasRenderingContext2D.drawImage().
Beispiele
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
| Spezifikation |
|---|
| HTML # dom-offscreencanvas-transfertoimagebitmap-dev |
Browser-Kompatibilität
Siehe auch
- Die Schnittstelle, die diese Methode definiert,
OffscreenCanvas ImageBitmapRenderingContext.transferFromImageBitmap