HTMLCanvasElement : méthode getContext()

Syntaxe

getContext(contextType)
getContext(contextType, contextAttributes)

Paramètres

contextType

Une chaîne de caractères contenant l'identifiant de contexte définissant le contexte de dessin associé au canevas. Les valeurs possibles sont :

"2d"

Crée un objet CanvasRenderingContext2D représentant un contexte de représentation bidimensionnel.

"webgl" (ou "experimental-webgl")

Crée un objet WebGLRenderingContext représentant un contexte de représentation tridimensionnel. Ce contexte n'est disponible que sur les navigateurs implémentant la version 1 de WebGL (OpenGL ES 2.0).

"webgl2"

Crée un objet WebGL2RenderingContext représentant un contexte de représentation tridimensionnel. Ce contexte n'est disponible que sur les navigateurs implémentant la version 2 de WebGL (OpenGL ES 3.0).

"webgpu"

Crée un objet GPUCanvasContext représentant un contexte de rendu pour les pipelines WebGPU. Ce contexte n'est disponible que sur les navigateurs implémentant l'API WebGPU.

"bitmaprenderer"

Crée un ImageBitmapRenderingContext qui ne fournit que la fonctionnalité de remplacement du contenu du canevas par une ImageBitmap donnée.

Note : L'identifiant "experimental-webgl" est utilisé dans les nouvelles implémentations de WebGL. Ces implémentations n'ont pas encore atteint la conformité à la suite de tests, ou les pilotes graphiques sur la plateforme ne sont pas encore stables. Le Khronos Group ^(angl.) certifie les implémentations WebGL selon certaines règles de conformité ^(angl.).

contextAttributes Facultatif

Vous pouvez utiliser plusieurs attributs de contexte lors de la création de votre contexte de rendu, par exemple :

js

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

Attributs du contexte 2D :

alpha

Valeur booléenne indiquant si le canevas contient un canal alpha. Si la valeur est false, l'agent utilisateur sait que l'arrière-plan est toujours opaque, ce qui peut accélérer le rendu de contenus et d'images transparentes.

colorSpace Facultatif

Définit l'espace colorimétrique du contexte de rendu. Valeurs possibles :

• "srgb" sélectionne l'espace colorimétrique sRGB. C'est la valeur par défaut.
• "display-p3" sélectionne l'espace colorimétrique display-p3.

colorType Facultatif

Définit le type de couleur du contexte de rendu. Valeurs possibles :

• "unorm8" définit les canaux de couleur sur des valeurs entières non signées sur 8 bits (valeur par défaut).
• "float16" définit les canaux de couleur sur des valeurs en virgule flottante 16 bits.

desynchronized

Valeur booléenne suggérant à l'agent utilisateur de réduire la latence en désynchronisant le cycle de peinture du canevas de la boucle d'évènements.

willReadFrequently

Valeur booléenne indiquant si de nombreuses opérations de lecture sont prévues. Cela forcera l'utilisation d'un canevas 2D logiciel (plutôt que matériel) et peut réduire l'utilisation mémoire lors d'appels fréquents à getImageData().

Attributs du contexte WebGL :

alpha

Valeur booléenne indiquant si le canevas contient un tampon alpha.

depth

Valeur booléenne indiquant que le tampon de dessin doit posséder un tampon de profondeur d'au moins 16 bits.

stencil

Valeur booléenne indiquant que le tampon de dessin doit posséder un tampon stencil d'au moins 8 bits.

desynchronized

Valeur booléenne suggérant à l'agent utilisateur de réduire la latence en désynchronisant le cycle de peinture du canevas.

antialias

Valeur booléenne indiquant s'il faut tenter de réaliser de l'anti-aliasing.

failIfMajorPerformanceCaveat

Valeur booléenne indiquant si la création du contexte doit échouer lorsque les performances système sont faibles ou qu'aucun GPU matériel n'est disponible.

powerPreference

Indication à l'agent utilisateur sur la configuration GPU souhaitée pour le contexte WebGL. Valeurs possibles :

"default"

Laisser l'agent utilisateur décider de la configuration GPU la plus adaptée (valeur par défaut).

"high-performance"

Priorise les performances de rendu par rapport à la consommation d'énergie.

"low-power"

Priorise l'économie d'énergie par rapport aux performances de rendu.

premultipliedAlpha

Valeur booléenne indiquant que le composeur de page supposera que le tampon de dessin contient des couleurs avec alpha pré-multiplié.

preserveDrawingBuffer

Si la valeur est vraie, les tampons ne seront pas effacés et conserveront leurs valeurs jusqu'à ce qu'ils soient effacés ou réécrits par l'auteur·ice.

xrCompatible

Valeur booléenne suggérant à l'agent utilisateur d'utiliser un adaptateur graphique compatible pour un appareil XR immersif. Il est déconseillé de définir ce drapeau de manière synchrone à la création du contexte ; préférez appeler la méthode asynchrone WebGLRenderingContext.makeXRCompatible() au moment où vous prévoyez de démarrer une session XR.

Note : La spécification WebGPU ne définit pas d'attributs spécifiques pour getContext(). Elle propose plutôt des options de configuration via la méthode GPUCanvasContext.configure().

Valeur retournée

Un contexte de rendu, qui est soit un

• CanvasRenderingContext2D pour "2d",
• WebGLRenderingContext pour "webgl" et "experimental-webgl",
• WebGL2RenderingContext pour "webgl2",
• GPUCanvasContext pour "webgpu",
• ImageBitmapRenderingContext pour "bitmaprenderer".

Si l'identifiant de contexte n'est pas pris en charge, ou si le canevas a déjà été configuré pour un autre mode de contexte, null est retourné.

Exceptions

InvalidStateError DOMException

Est levée si le canevas a transféré son contrôle à un OffscreenCanvas en appelant HTMLCanvasElement.transferControlToOffscreen().

Exemples

Étant donné l'élément HTML <canvas> :

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

vous pouvez obtenir un contexte 2d du canevas grâce au code suivant :

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

Vous avez alors le contexte 2D de représentation pour un canevas, et vous pouvez dessiner à l'intérieur.

Spécifications

Compatibilité des navigateurs

Voir aussi

• HTMLCanvasElement : Interface définissant la méthode HTMLCanvasElement.getContext()
• La méthode OffscreenCanvas.getContext()
• Les méthodes CanvasRenderingContext2D.getContextAttributes(), WebGLRenderingContext.getContextAttributes()
• Contextes de représentation disponibles : CanvasRenderingContext2D, ImageBitmapRenderingContext, WebGLRenderingContext, WebGL2RenderingContext, GPUCanvasContext
• Espace colorimétrique DCI-P3
• Espace colorimétrique sRGB