Signatur
Beschreibung
createImageBitmap() steht in Workern als globale Funktion bereit (self.createImageBitmap()). Die Methode dekodiert eine Bildquelle, etwa einen Blob, ein ImageData, ein OffscreenCanvas, ein VideoFrame oder ein vorhandenes ImageBitmap, und liefert ein Promise, das mit einem ImageBitmap erfüllt wird. Dieses Bitmap lässt sich ohne Verzögerung auf ein OffscreenCanvas zeichnen oder als WebGL-Textur hochladen.
Die Methode eignet sich vor allem dafür, das aufwendige Dekodieren von Bildern aus dem Haupt-Thread herauszuhalten. Typische Fälle sind Bildergalerien, Thumbnail-Erzeugung, Spiele mit vielen Texturen und Bildverarbeitung in einem OffscreenCanvas. Ein ImageBitmap ist ein übertragbares Objekt (Transferable). Du kannst es also per postMessage() ohne Kopie an den Haupt-Thread zurückgeben.
Mit den optionalen Parametern sx, sy, sw und sh legst du einen Ausschnitt der Quelle fest. Über options steuerst du Skalierung (resizeWidth/resizeHeight, resizeQuality), vertikale Spiegelung (imageOrientation), Vormultiplikation des Alphakanals (premultiplyAlpha) und Farbraum-Umwandlung (colorSpaceConversion).
Im Worker gibt es kein DOM. Die Quellen HTMLImageElement, HTMLVideoElement, HTMLCanvasElement und SVGImageElement fallen dort also weg. Bilder lädst du stattdessen per fetch() als Blob.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | Blob | ImageData | ImageBitmap | OffscreenCanvas | VideoFrame | Die Bildquelle. Im Worker sind nur Quellen ohne DOM-Bezug möglich. | |
| $sx | number | x-Koordinate der linken oberen Ecke des Ausschnitts. Gibst du einen Ausschnitt an, sind alle vier Werte sx, sy, sw und sh Pflicht. |
|
| $sy | number | y-Koordinate der linken oberen Ecke des Ausschnitts. | |
| $sw | number | Breite des Ausschnitts in Pixeln. Der Wert darf nicht 0 sein. Negative Werte spiegeln den Ausschnitt in die andere Richtung. | |
| $sh | number | Höhe des Ausschnitts in Pixeln. Der Wert darf nicht 0 sein. | |
| $options | object | {} | Optionen:
|
Rückgabewert
Promise, das mit dem erzeugten ImageBitmap erfüllt wird. Es wird abgelehnt, wenn die Quelle ungültig ist oder nicht dekodiert werden kann (InvalidStateError, InvalidStateError/EncodingError bei defekten Daten), wenn sw oder sh gleich 0 ist (RangeError) oder wenn der Typ der Quelle nicht unterstützt wird (TypeError).Beispiele
Bild im Worker laden, dekodieren und an den Haupt-Thread übertragen
// worker.js
self.addEventListener('message', async (event) => {
const response = await fetch(event.data.url);
const blob = await response.blob();
const bitmap = await createImageBitmap(blob);
// Ohne Kopie übertragen (Transferable)
self.postMessage({ bitmap }, [bitmap]);
});
// main.js
const worker = new Worker('worker.js');
worker.addEventListener('message', ({ data }) => {
const ctx = document.querySelector('canvas').getContext('2d');
ctx.drawImage(data.bitmap, 0, 0);
console.log(`Bitmap: ${data.bitmap.width}×${data.bitmap.height}`);
data.bitmap.close();
});
worker.postMessage({ url: '/img/foto.jpg' });Thumbnail mit Ausschnitt und Skalierung erzeugen
// worker.js – quadratisches 200×200-Thumbnail aus der Bildmitte
const makeThumbnail = async (blob) => {
const full = await createImageBitmap(blob);
const side = Math.min(full.width, full.height);
const sx = (full.width - side) / 2;
const sy = (full.height - side) / 2;
full.close();
const thumb = await createImageBitmap(blob, sx, sy, side, side, {
resizeWidth: 200,
resizeHeight: 200,
resizeQuality: 'high'
});
const canvas = new OffscreenCanvas(200, 200);
canvas.getContext('2d').drawImage(thumb, 0, 0);
thumb.close();
return canvas.convertToBlob({ type: 'image/webp', quality: 0.8 });
};
self.onmessage = async ({ data }) => {
const thumbBlob = await makeThumbnail(data.file);
self.postMessage(thumbBlob);
};Pixeldaten bearbeiten und als Bitmap zurückgeben
// worker.js – Graustufen-Filter über ImageData
const toGrayscale = async (imageData) => {
const { data } = imageData;
for (let i = 0; i < data.length; i += 4) {
const g = 0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2];
data[i] = data[i + 1] = data[i + 2] = g;
}
return createImageBitmap(imageData);
};
const demo = new ImageData(new Uint8ClampedArray([255, 0, 0, 255]), 1, 1);
toGrayscale(demo).then((bmp) => console.log(bmp.width, bmp.height));Fehlerbehandlung bei ungültigen Bilddaten
// worker.js
const safeDecode = async (blob) => {
try {
return await createImageBitmap(blob);
} catch (err) {
console.warn(`Dekodierung fehlgeschlagen: ${err.name}`);
return null;
}
};
safeDecode(new Blob(['kein Bild'], { type: 'image/png' }))
.then((result) => console.log(result));