Signatur
Window.createImageBitmap(image, sx?, sy?, sw?, sh?, options?)
Beschreibung
createImageBitmap() nimmt eine Bildquelle entgegen, etwa ein <img>, <video>, <canvas>, Blob, ImageData, OffscreenCanvas, VideoFrame oder ein vorhandenes ImageBitmap. Daraus erzeugt die Methode ein ImageBitmap. Das ist ein bereits dekodiertes Bild, das ohne weitere Verzögerung mit drawImage() auf ein Canvas gezeichnet oder als WebGL-Textur hochgeladen werden kann.
Der große Vorteil ist, dass das Dekodieren asynchron läuft und den Hauptthread nicht blockiert. Die Methode gibt es auch in Web Workern (self.createImageBitmap()). Deshalb eignet sie sich gut für Spiele, Sprite-Sheets, Bildbearbeitung und Rendering mit OffscreenCanvas. Ein ImageBitmap ist außerdem transferierbar: Mit postMessage() lässt es sich ohne Kopie zwischen Worker und Hauptthread übergeben.
Mit den optionalen Parametern sx, sy, sw und sh schneidest du ein Rechteck aus der Quelle aus. Das ist praktisch, um einzelne Kacheln aus einem Sprite-Sheet zu lösen. Über das options-Objekt steuerst du Skalierung (resizeWidth, resizeHeight, resizeQuality), Spiegelung (imageOrientation), Alpha-Behandlung (premultiplyAlpha) und Farbraum-Konvertierung (colorSpaceConversion).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | HTMLImageElement|SVGImageElement|HTMLVideoElement|HTMLCanvasElement|Blob|ImageData|ImageBitmap|OffscreenCanvas|VideoFrame | Die Bildquelle, aus der das Bitmap erzeugt wird. | |
| $sx | number | X-Koordinate des Ausschnitts in Quellpixeln. Wird nur zusammen mit sy, sw und sh angegeben. |
|
| $sy | number | Y-Koordinate des Ausschnitts. | |
| $sw | number | Breite des Ausschnitts. Darf nicht 0 sein, sonst wird ein RangeError geworfen. |
|
| $sh | number | Höhe des Ausschnitts. Darf nicht 0 sein. |
|
| $options | object | {} | Optionen:
|
Rückgabewert
Typ
Promise<ImageBitmap>
Beschreibung
Ein Promise, das mit dem fertig dekodierten
ImageBitmap erfüllt wird. Bei ungültiger Quelle wird es abgelehnt, etwa mit InvalidStateError oder TypeError. Das gilt auch bei einem Ausschnitt der Größe 0 (RangeError) und bei nicht dekodierbaren Daten.Beispiele
Bild per fetch laden und auf ein Canvas zeichnen
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const loadBitmap = async (url) => {
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();
return createImageBitmap(blob);
};
const bitmap = await loadBitmap('/img/logo.png');
canvas.width = bitmap.width;
canvas.height = bitmap.height;
ctx.drawImage(bitmap, 0, 0);
console.log(`Gezeichnet: ${bitmap.width}×${bitmap.height}`);
bitmap.close(); // Speicher sofort freigebenGezeichnet: 256×256
Sprite-Sheet in einzelne Kacheln zerlegen
const img = new Image();
img.src = '/img/sprites.png'; // z. B. 4 Kacheln à 32×32 in einer Reihe
await img.decode();
const TILE = 32;
const sprites = await Promise.all(
Array.from({ length: 4 }, (_, i) =>
createImageBitmap(img, i * TILE, 0, TILE, TILE)
)
);
const ctx = document.querySelector('canvas').getContext('2d');
sprites.forEach((sprite, i) => ctx.drawImage(sprite, i * 40, 10));
console.log(sprites.length, sprites[0].width);4 32
Thumbnail im Web Worker erzeugen
// worker.js
self.onmessage = async ({ data: file }) => {
const thumb = await createImageBitmap(file, {
resizeWidth: 200,
resizeQuality: 'high'
});
// ImageBitmap ohne Kopie an den Hauptthread übertragen
self.postMessage(thumb, [thumb]);
};
// main.js
const worker = new Worker('worker.js');
const input = document.querySelector('input[type=file]');
input.addEventListener('change', () => worker.postMessage(input.files[0]));
worker.onmessage = ({ data: bitmap }) => {
const ctx = document.querySelector('canvas').getContext('bitmaprenderer');
ctx.transferFromImageBitmap(bitmap);
};Textur für WebGL vertikal spiegeln
const blob = await (await fetch('/textures/stone.jpg')).blob();
const texBitmap = await createImageBitmap(blob, {
imageOrientation: 'flipY',
premultiplyAlpha: 'none',
colorSpaceConversion: 'none'
});
const gl = document.querySelector('canvas').getContext('webgl2');
const tex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, tex);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, texBitmap);
gl.generateMipmap(gl.TEXTURE_2D);// Wichtig · Fallstricke
- Speicher: Ein
ImageBitmaphält die dekodierten Pixel im Speicher, oft im GPU-Speicher. Rufebitmap.close()auf, sobald du es nicht mehr brauchst. Das ist besonders wichtig in Schleifen und bei Videoframes. - CORS: Stammt die Quelle von einer fremden Domain und fehlt die CORS-Freigabe, wird das Bitmap als tainted markiert. Zeichnen funktioniert dann zwar, aber
getImageData()undtoDataURL()werfen einenSecurityError. Setzeimg.crossOrigin = 'anonymous', oder hole die Daten perfetchmit passenden CORS-Headern. - Ladezustand: Ein
HTMLImageElementmuss vollständig geladen sein, sonst schlägt der Aufruf mitInvalidStateErrorfehl. Warte vorher aufawait img.decode(). - SVG-Blobs: Ein
Blobmit SVG-Inhalt wird von den meisten Browsern nicht unterstützt. Lade das SVG in diesem Fall über ein<img>-Element. - Kompatibilität: Die Methode selbst funktioniert in allen modernen Browsern. Safari unterstützt sie erst ab Version 15 vollständig, und die Optionen
resizeWidth,resizeHeightundresizeQualityfunktionieren in älteren Safari- und Firefox-Versionen teilweise nicht. Die WerteimageOrientation: \"none\"und\"default\"sind veraltet. Nutze stattdessen\"from-image\"bzw.\"flipY\". - Negative Werte für
swodershsind erlaubt. Der Ausschnitt verläuft dann vonsx/syaus nach links bzw. oben.