OffscreenCanvas.getContext() — Methode · JavaScript-Referenz

Signatur

OffscreenCanvas.prototype.getContext(contextType, contextAttributes)

Beschreibung

getContext() liefert den Zeichenkontext eines OffscreenCanvas. Über diesen Kontext wird gezeichnet, genauso wie bei einem normalen <canvas>-Element. Der Unterschied: Ein OffscreenCanvas hängt nicht am DOM. Es kann deshalb in einem Web Worker laufen und aufwendiges Rendering vom Haupt-Thread fernhalten.

Welcher Kontext entsteht, bestimmt der erste Parameter: "2d" liefert einen OffscreenCanvasRenderingContext2D, "webgl" und "webgl2" liefern WebGL-Kontexte, "webgpu" einen GPUCanvasContext und "bitmaprenderer" einen ImageBitmapRenderingContext. Rufen Sie die Methode später erneut mit demselben Typ auf, bekommen Sie dasselbe Kontextobjekt zurück. Die Attribute des zweiten Aufrufs werden dabei ignoriert.

Ein Canvas kann immer nur einen Kontexttyp haben. Wurde zum Beispiel schon ein "2d"-Kontext angelegt, gibt ein späterer Aufruf mit "webgl" null zurück. Typische Einsatzfälle sind Spiele, Datenvisualisierung, Bildverarbeitung und Diagramme, die im Worker gerendert werden. Die Anzeige läuft dann entweder über transferControlToOffscreen() (Ergebnisse erscheinen automatisch im sichtbaren Canvas) oder über transferToImageBitmap() / convertToBlob().

Parameter

Name	Typ	Default	Beschreibung
$contextType Pflicht	"2d" \| "webgl" \| "webgl2" \| "webgpu" \| "bitmaprenderer"		Art des gewünschten Zeichenkontexts. Anders als bei `HTMLCanvasElement` gibt es kein `"experimental-webgl"`.
$contextAttributes	object	{}	Optionen für den Kontext, z. B. bei `"2d"`: `alpha`, `willReadFrequently`, `colorSpace`; bei WebGL: `antialias`, `depth`, `preserveDrawingBuffer`, `powerPreference` u. a.

Rückgabewert

Typ

Beschreibung

Das Kontextobjekt, oder null, wenn der Typ nicht unterstützt wird oder das Canvas schon einen Kontext eines anderen Typs hat.

Beispiele

2D-Kontext erzeugen und als Blob exportieren

const canvas = new OffscreenCanvas(200, 100);
const ctx = canvas.getContext('2d');

ctx.fillStyle = '#0066cc';
ctx.fillRect(0, 0, 200, 100);
ctx.fillStyle = '#fff';
ctx.font = '20px sans-serif';
ctx.fillText('Hallo Offscreen', 20, 55);

const blob = await canvas.convertToBlob({ type: 'image/png' });
console.log(blob.type, blob.size > 0);

image/png true

Rendering im Web Worker per transferControlToOffscreen()

// main.js
const htmlCanvas = document.querySelector('#chart');
const offscreen = htmlCanvas.transferControlToOffscreen();
const worker = new Worker('render-worker.js');
worker.postMessage({ canvas: offscreen }, [offscreen]);

// render-worker.js
self.onmessage = ({ data }) => {
  const ctx = data.canvas.getContext('2d');
  let x = 0;
  const draw = () => {
    ctx.clearRect(0, 0, data.canvas.width, data.canvas.height);
    ctx.fillStyle = 'tomato';
    ctx.fillRect(x, 40, 50, 50);
    x = (x + 2) % data.canvas.width;
    requestAnimationFrame(draw); // in Workern verfügbar
  };
  draw();
};

WebGL2 mit Fallback und Kontextkonflikt

const canvas = new OffscreenCanvas(256, 256);
const gl = canvas.getContext('webgl2', { antialias: false })
  ?? canvas.getContext('webgl');

if (!gl) {
  console.log('WebGL wird nicht unterstützt');
} else {
  gl.clearColor(0, 0.5, 0, 1);
  gl.clear(gl.COLOR_BUFFER_BIT);
  // Anderer Kontexttyp auf demselben Canvas ist nicht möglich:
  console.log(canvas.getContext('2d'));
  // Gleicher Typ liefert dasselbe Objekt:
  console.log(canvas.getContext(gl instanceof WebGL2RenderingContext ? 'webgl2' : 'webgl') === gl);
}

null true

bitmaprenderer: fertige Frames anzeigen

const worker = new OffscreenCanvas(300, 150);
const wctx = worker.getContext('2d');
wctx.fillStyle = 'purple';
wctx.fillRect(0, 0, 300, 150);
const bitmap = worker.transferToImageBitmap();

const view = document.querySelector('canvas');
view.getContext('bitmaprenderer').transferFromImageBitmap(bitmap);

// Wichtig · Fallstricke

Ein Kontexttyp pro Canvas: Sobald ein Kontext existiert, liefert jeder andere Typ null. Prüfen Sie den Rückgabewert immer.
Wird getContext() aufgerufen, nachdem das OffscreenCanvas per postMessage übertragen wurde (Zustand „detached“), wirft die Methode einen InvalidStateError (DOMException).
Auf einem <canvas>, das bereits einen Kontext hat, schlägt transferControlToOffscreen() fehl. Deshalb erst übertragen, dann im Worker getContext() aufrufen.
"experimental-webgl" gibt es hier nicht. "webgpu" braucht einen Browser mit WebGPU-Unterstützung.
Kompatibilität: 2D-Kontext in Chrome 69+, Firefox 105+ und Safari 16.4+. WebGL-Kontexte in Safari erst ab Version 17. Für ältere Umgebungen gibt es die Merkmalserkennung typeof OffscreenCanvas !== 'undefined'.
Performance: Setzen Sie willReadFrequently: true, wenn Sie häufig getImageData() aufrufen. Dann kann der Browser auf CPU-Rendering optimieren.

Siehe auch

OffscreenCanvas HTMLCanvasElement.getContext() HTMLCanvasElement.transferControlToOffscreen() OffscreenCanvas.transferToImageBitmap() OffscreenCanvas.convertToBlob() OffscreenCanvasRenderingContext2D WebGL2RenderingContext ImageBitmapRenderingContext