HTMLCanvasElement: getContext() Methode

contextType

Ein String, der den Kontextbezeichner enthält, der den mit dem Canvas verbundenen Zeichenkontext definiert. Mögliche Werte sind:

"2d"

Erstellt ein CanvasRenderingContext2D Objekt, das einen zweidimensionalen Zeichenkontext darstellt.

"webgl" (oder "experimental-webgl")

Erstellt ein WebGLRenderingContext Objekt, das einen dreidimensionalen Zeichenkontext darstellt. Dieser Kontext ist nur in Browsern verfügbar, die WebGL Version 1 (OpenGL ES 2.0) implementieren.

"webgl2"

Erstellt ein WebGL2RenderingContext Objekt, das einen dreidimensionalen Zeichenkontext darstellt. Dieser Kontext ist nur in Browsern verfügbar, die WebGL Version 2 (OpenGL ES 3.0) implementieren.

"webgpu"

Erstellt ein GPUCanvasContext Objekt, das einen dreidimensionalen Zeichenkontext für WebGPU-Renderpipelines darstellt. Dieser Kontext ist nur in Browsern verfügbar, die The WebGPU API implementieren.

"bitmaprenderer"

Erstellt einen ImageBitmapRenderingContext, der nur Funktionalität zum Ersetzen des Canvas-Inhalts mit einem gegebenen ImageBitmap bietet.

Hinweis: Der Bezeichner "experimental-webgl" wird in neuen Implementierungen von WebGL verwendet. Diese Implementierungen haben entweder noch nicht die Testsuiten-Konformität erreicht, oder die Grafiktreiber auf der Plattform sind noch nicht stabil. Die Khronos Group zertifiziert WebGL-Implementierungen unter bestimmten Konformitätsregeln.

contextAttributes Optional

Sie können mehrere Kontextattribute beim Erstellen Ihres Zeichenkontexts verwenden, zum Beispiel:

js

const gl = canvas.getContext("webgl", {
  antialias: false,
  depth: false,
});

2d-Kontextattribute:

alpha

Ein boolescher Wert, der angibt, ob das Canvas einen Alphakanal enthält. Wenn false gesetzt ist, weiß der Browser nun, dass der Hintergrund immer undurchsichtig ist, was das Zeichnen von transparentem Inhalt und Bildern beschleunigen kann.

colorSpace Optional

Gibt den Farbraum des Zeichenkontexts an. Mögliche Werte sind:

• "srgb" wählt den sRGB Farbraum. Dies ist der Standardwert.
• "display-p3" wählt den display-p3 Farbraum.

desynchronized

Ein boolescher Wert, der den Benutzeragenten anweist, die Latenz zu verringern, indem der Canvas-Zeichenzyklus vom Ereignisloop desynchronisiert wird.

willReadFrequently

Ein boolescher Wert, der angibt, ob viele Ausleseoperationen geplant sind. Dies erzwingt die Verwendung eines Software- (anstelle eines hardwarebeschleunigten) 2D-Canvas und kann Speicher sparen, wenn getImageData() häufig aufgerufen wird.

WebGL-Kontextattribute:

alpha

Ein boolescher Wert, der angibt, ob das Canvas einen Alphapuffer enthält.

depth

Ein boolescher Wert, der anzeigt, dass der Zeichenpuffer einen Tiefenpuffer von mindestens 16 Bit haben soll.

stencil

Ein boolescher Wert, der anzeigt, dass der Zeichenpuffer einen Schablonenpuffer von mindestens 8 Bit haben soll.

desynchronized

Ein boolescher Wert, der den Benutzeragenten anweist, die Latenz zu verringern, indem der Canvas-Zeichenzyklus vom Ereignisloop desynchronisiert wird.

antialias

Ein boolescher Wert, der angibt, ob Antialiasing nach Möglichkeit durchgeführt werden soll.

failIfMajorPerformanceCaveat

Ein boolescher Wert, der angibt, ob ein Kontext erstellt wird, wenn die Systemleistung niedrig ist oder kein Hardware-GPU verfügbar ist.

powerPreference

Ein Hinweis an den Benutzeragenten, welche GPU-Konfiguration für den WebGL-Kontext geeignet ist. Mögliche Werte sind:

"default"

Überlässt dem Benutzeragenten die Entscheidung, welche GPU-Konfiguration am besten geeignet ist. Dies ist der Standardwert.

"high-performance"

Priorisiert die Renderleistung gegenüber dem Stromverbrauch.

"low-power"

Priorisiert den Stromverbrauch gegenüber der Renderleistung.

premultipliedAlpha

Ein boolescher Wert, der angibt, dass der Seitenkompositor davon ausgehen wird, dass der Zeichenpuffer Farben mit vor-multipliziertem Alpha enthält.

preserveDrawingBuffer

Wenn der Wert true ist, werden die Puffer nicht gelöscht und ihre Werte bleiben erhalten, bis sie vom Autor gelöscht oder überschrieben werden.

xrCompatible

Ein boolescher Wert, der den Benutzeragenten darauf hinweist, einen kompatiblen Grafikadapter für ein immersives XR-Gerät zu verwenden. Das Setzen dieser synchronen Markierung bei der Kontexterstellung wird nicht empfohlen; stattdessen sollte die asynchrone Methode WebGLRenderingContext.makeXRCompatible() aufgerufen werden, sobald Sie beabsichtigen, eine XR-Sitzung zu starten.

Hinweis: Die WebGPU-Spezifikation definiert keine spezifischen Kontextattribute für getContext(). Stattdessen bietet sie Konfigurationsoptionen über die Methode GPUCanvasContext.configure() an.

Ein Zeichenkontext, der entweder ist:

• CanvasRenderingContext2D für "2d",
• WebGLRenderingContext für "webgl" und "experimental-webgl",
• WebGL2RenderingContext für "webgl2",
• GPUCanvasContext für "webgpu",
• ImageBitmapRenderingContext für "bitmaprenderer".

Wenn der Kontextbezeichner nicht unterstützt wird oder das Canvas bereits auf einen anderen Kontextmodus gesetzt wurde, wird null zurückgegeben.

InvalidStateError DOMException

Wird ausgelöst, wenn das Canvas seine Kontrolle über einen Aufruf von HTMLCanvasElement.transferControlToOffscreen() übertragen hat.

Gegeben ist dieses <canvas> Element:

<canvas id="canvas" width="300" height="300"></canvas>

Sie können einen 2d-Kontext des Canvas mit folgendem Code erhalten:

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
console.log(ctx); // CanvasRenderingContext2D { /* … */ }

Jetzt haben Sie den 2D-Zeichenkontext für ein Canvas und können darin zeichnen.

• HTMLCanvasElement: Schnittstelle zur Definition der HTMLCanvasElement.getContext() Methode
• OffscreenCanvas.getContext()
• CanvasRenderingContext2D.getContextAttributes(), WebGLRenderingContext.getContextAttributes()
• CanvasRenderingContext2D, ImageBitmapRenderingContext, WebGLRenderingContext, WebGL2RenderingContext, GPUCanvasContext: Verfügbare Zeichenkontexte
• DCI-P3 Farbraum auf Wikipedia
• sRGB Farbraum auf Wikipedia