Les nuanceurs WebGL fournissent des effets visuels puissants accélérés par GPU, permettant des fonctionnalités avancées telles que les distorsions d'ondulation dynamiques, les modèles d'éclairage, l'étalonnage des couleurs et les transformations de sommets personnalisées. L'API HTML-in-Canvas permet aux développeurs d'appliquer des textures WebGL au contenu HTML. Cela permet d'appliquer de manière native des nuanceurs de fragments et de sommets hautes performances à des composants d'interface utilisateur entièrement interactifs, tels que des boutons, des champs de saisie et du texte enrichi, tout en conservant l'accessibilité native, la sélection de texte et la gestion des événements DOM.
Mise en œuvre
Vérifiez si le navigateur est compatible avec HTML-in-Canvas :
if ('content' in HTMLCanvasElement.prototype) { // Use HTML in Canvas API } else { // Use fallback strategy }Ajoutez l'attribut
content="drawable"à l'élément HTML<canvas>.Placez votre contenu HTML dans l'élément
<canvas>et ajoutez l'attributdrawableà chaque élément que vous dessinez. Un élément avecdrawablecapture sa sous-arborescence, à l'exception des descendants imbriqués qui sont égalementdrawable.<canvas id="canvas" content="drawable"> <div id="html-content" drawable></div> </canvas>Mettez à l'échelle la grille de votre canevas pour qu'elle corresponde au facteur de scaling de l'appareil afin d'éviter le flou :
const observer = new ResizeObserver(([entry]) => { const dpc = entry.devicePixelContentBoxSize; canvas.width = dpc ? dpc[0].inlineSize : Math.round(entry.contentRect.width * window.devicePixelRatio); canvas.height = dpc ? dpc[0].blockSize : Math.round(entry.contentRect.height * window.devicePixelRatio); }); const supportsDevicePixelContentBox = typeof ResizeObserverEntry !== "undefined" && "devicePixelContentBoxSize" in ResizeObserverEntry.prototype; const options = supportsDevicePixelContentBox ? { box: "device-pixel-content-box" } : {}; observer.observe(canvas, options);Préallouez d'abord la texture à l'aide de la méthode
texImage2D. Les extraits de ce guide utilisent un contexte WebGL 2 (canvas.getContext("webgl2")).
Allouez d'abord de l'espace de stockage pour les textures en appelant texImage2D() avec null au lieu des données de pixels. Cela réserve de la mémoire GPU de la taille et du format indiqués sans importer de pixels. Suivez les règles ci-dessous :
- Définissez la taille de la texture à partir de
canvas.captureElementImage(element). Ses valeurswidthetheightsont exprimées en pixels de la grille du canevas (backing store). Arrondissez-les donc avecMath.ceil().captureElementImage()génère une exception si l'élément n'a pas encore d'enregistrement de peinture : appelezrequestPaint(), puis réessayez lors de l'événementpaintsuivant. - N'allouez le niveau 0 que lors de la première importation ou lorsque la taille change, car la réallocation efface la texture. Utilisez un stockage modifiable : le stockage
texStorage2D()immuable ne peut pas être redimensionné lorsque l'élément change de taille.
// Returns the element's size in canvas grid pixels, or null if the element
// has no paint record yet.
function getElementImageSize(canvas, element) {
let elementImage;
try {
elementImage = canvas.captureElementImage(element);
} catch (err) {
canvas.requestPaint(); // No paint record yet: retry on the next paint event.
return null;
}
const width = Math.ceil(elementImage.width);
const height = Math.ceil(elementImage.height);
elementImage.close();
return width > 0 && height > 0 ? { width, height } : null;
}
// Binds the texture, and allocates its storage on the first upload, and when
// the element size changes. `state` stores the allocated size.
function allocateElementTexture(gl, texture, state, width, height) {
gl.bindTexture(gl.TEXTURE_2D, texture);
if (state.width === width && state.height === height) return;
gl.texImage2D(
gl.TEXTURE_2D,
0, // Mipmap level
gl.RGBA8, // Internal format: 8 bits per RGBA channel
width, // Size in canvas grid pixels
height,
0, // Border: must be 0
gl.RGBA, // Format and type that match RGBA8
gl.UNSIGNED_BYTE,
null // null reserves GPU memory without uploading pixels
);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
state.width = width;
state.height = height;
}
const texture = gl.createTexture();
const textureState = { width: 0, height: 0 };
Affichez le contenu HTML dans la texture à l'intérieur d'un gestionnaire d'événements
canvas.onpaintà l'aide de la méthodetexElementSubImage2D. Suivez les règles ci-dessous :- Un élément ne peut être importé qu'une fois qu'il a été peint par le canevas. Importez à partir de l'événement
paintet appelezcanvas.requestPaint()pour en demander un. - Transmettez
{ width, height }dans la configuration. La copie remplit la texture allouée, quelle que soit la mise à l'échelle du canevas. - Réallouez la texture si la taille a changé, comme indiqué à l'étape 5.
- Un élément ne peut être importé qu'une fois qu'il a été peint par le canevas. Importez à partir de l'événement
// Uploads the element into the texture. Returns false if the element has no
// paint record yet. In that case, it's uploaded on the next paint event.
function uploadElementWebGL(gl, canvas, texture, element, state) {
const size = getElementImageSize(canvas, element);
if (!size) return false;
const { width, height } = size;
// Bind the texture, and reallocate it if the size changed (step 5).
allocateElementTexture(gl, texture, state, width, height);
gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element, { width, height });
return true;
}
canvas.onpaint = () => {
try {
uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
} catch (err) {
console.error('texElementSubImage2D copy failed:', err);
}
};
Lorsque vous utilisez une boucle requestAnimationFrame pour afficher la scène, appelez canvas.requestPaint() dans la boucle pour vous assurer que le contenu HTML est affiché sur le canevas. event.changedElements liste les éléments dont l'affichage a changé. Veillez à ne réimporter la texture que si les éléments HTML descendants ont été mis à jour :
function render() {
// Request to update the canvas
canvas.requestPaint();
requestAnimationFrame(render);
}
requestAnimationFrame(render);
canvas.onpaint = (event) => {
if (event.changedElements && event.changedElements.length > 0) {
// Update the texture with uploadElementWebGL()
}
// Render the scene, and sync the element geometry as shown in step 7
};
- Synchronisez la géométrie de l'élément.
Calculez un DOMMatrix qui mappe la zone de bordure de l'élément, en pixels CSS, au canevas, en pixels CSS. Le navigateur doit mapper l'espace de coordonnées 3D vers l'espace de coordonnées CSS à l'aide d'une transformation de fenêtre d'affichage. Pour ce faire, procédez comme suit :
- Normalisez l'élément HTML. Les éléments HTML sont dimensionnés en pixels (par exemple, 200 px de large). Cependant, WebGL traite généralement les objets comme des "carrés unitaires", par exemple, allant de -0,5 à 0,5. Si vous ne normalisez pas, votre bouton de 200 px sera 200 fois plus grand. Cette étape inverse également l'axe Y, car en CSS, le bas est positif, mais en WebGL, le haut est positif.
- Convertissez la matrice MVP WebGL en matrice DOM.
- Mappez sur la fenêtre d'affichage du canevas. Cette étape correspond à la phase de "redimensionnement" : elle étire à nouveau les calculs de l'espace unitaire pour qu'ils correspondent aux dimensions en pixels CSS de votre élément
<canvas>à l'écran, et inverse l'axe Y. Calculez la transformation finale. Multipliez les matrices dans l'ordre : Viewport * MVP * Normalisation. En les combinant en une seule transformation finale, on obtient une "carte" qui indique au navigateur l'emplacement exact de l'élément HTML pour qu'il s'aligne sur le dessin 3D. Le navigateur effectue la division de perspective.
// Maps the element's border box (CSS pixels) to the canvas (CSS pixels), for a // quad that spans -0.5 to 0.5 in model space and is drawn with the `mvp` matrix. function computeCanvasTransform(canvas, element, mvp) { const width = element.offsetWidth; const height = element.offsetHeight; // 1. Normalize the HTML element (CSS pixels -> WebGL Model Space) const toGLModel = new DOMMatrix() // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up) .scale(1 / width, -1 / height, 1 / height) // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling .translate(-width / 2, -height / 2); // 2. Convert WebGL MVP Matrix to DOM Matrix const mvpDOM = new DOMMatrix(Array.from(mvp)); // 3. Map to the canvas viewport, in CSS pixels const clipToCanvasViewport = new DOMMatrix() // Move center (0,0) to center of canvas .translate(canvas.clientWidth / 2, canvas.clientHeight / 2) // Scale normalized clip (-1..1) to viewport size, and flip Y back .scale(canvas.clientWidth / 2, -canvas.clientHeight / 2, canvas.clientHeight / 2); // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square) return clipToCanvasViewport.multiply(mvpDOM).multiply(toGLModel); }
Transmettez ensuite la transformation à canvas.updateElementGeometry() en tant que canvasTransform. L'élément HTML est alors placé directement au-dessus de ses pixels affichés. Cela garantit que lorsqu'un utilisateur clique sur un bouton ou sélectionne du texte, il interagit réellement avec l'élément HTML réel. Le navigateur utilise également la transformation pour les limites d'accessibilité de l'élément, par exemple pour les anneaux de sélection du lecteur d'écran :
canvas.updateElementGeometry(targetHTMLElement, {
canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
});
Utilisez ces options pour contrôler les tests de positionnement :
- Chaque appel
updateElementGeometry()déplace l'élément en haut de l'ordre de test de positionnement. Transmettez{ preserveHitTestOrder: true }pour conserver sa position. - Appelez
canvas.clearElementGeometry(element)pour supprimer un élément du test de positionnement, par exemple lorsque vous le masquez. - Transmettez
{ canvasClip }, unDOMRectInitdans l'espace de coordonnées decanvasTransform, pour limiter la zone de test de détection, par exemple lorsque seule une partie de l'élément est dessinée.
Exemple de code
<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
<div id="ui-element" drawable>
<p>WebGL UI Element</p>
<button>Action</button>
</div>
</canvas>
<script>
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl2");
const uiElement = document.getElementById("ui-element");
// getElementImageSize() and allocateElementTexture() are defined in step 5.
// uploadElementWebGL() is defined in step 6.
// computeCanvasTransform() is defined in step 7.
// Setup WebGL texture...
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
const textureState = { width: 0, height: 0 };
canvas.onpaint = () => {
// 1. Update texture with HTML content
try {
uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
} catch (err) {
console.error('texElementSubImage2D copy failed:', err);
}
// ... Render your 3D scene here, calculating htmlElementMVP matrix ...
// 2. Sync DOM position, hit testing, and accessibility bounds with 3D scene
canvas.updateElementGeometry(uiElement, {
canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
});
};
</script>
Bonnes pratiques
- OBLIGATOIRE : Vérifiez la compatibilité du navigateur avec l'API HTML-in-Canvas avant de l'utiliser.
- OBLIGATOIRE : Ajoutez toujours l'attribut
content="drawable"à l'élément<canvas>. - OBLIGATOIRE : ajoutez TOUJOURS l'attribut
drawableaux enfants directs du canevas. - OBLIGATOIRE : ajoutez l'attribut
drawableà chaque élément que vous souhaitez pouvoir dessiner indépendamment de ses éléments parents. - OBLIGATOIRE : utilisez un gestionnaire d'événements
onpaintpour afficher le contenu HTML sur le canevas. - OBLIGATOIRE : Pré-allouez le tampon de texture avec
texImage2D()une fois (lorsqu'il est initialisé ou lorsque la taille de l'élément change). Réallouez la texture uniquement lorsque la taille change et définissezTEXTURE_MIN_FILTERsurLINEAR. - OBLIGATOIRE : utilisez la méthode
texElementSubImage2Dpour afficher le contenu HTML dans une texture que vous pré-allouez avectexImage2D(), dimensionnée à partir decaptureElementImage(). - OBLIGATOIRE : synchronisez la géométrie de l'élément HTML avec le contenu affiché en appelant
canvas.updateElementGeometry(element, { canvasTransform }). - OBLIGATOIRE : Utilisez
ResizeObserverpour observer la taille de l'écran et mettre à jour la taille du canevas afin qu'elle corresponde aux pixels de l'appareil. - NE PAS intégrer de contenu interorigine dans un canevas, car cela n'est pas possible.
- N'INITIALISEZ PAS
ResizeObserverdans le gestionnaire d'événementsonpaint, car cela peut entraîner des fuites de mémoire.
Stratégies de remplacement
L'API HTML-in-Canvas n'est actuellement pas compatible avec tous les navigateurs récents. Une stratégie de remplacement est donc généralement nécessaire.
Toutefois, compte tenu des avantages de cette API en termes de performances, il est préférable d'utiliser HTML-in-Canvas si le navigateur le permet.
La stratégie de remplacement dépend du cas d'utilisation. Par exemple, pour un contenu HTML interactif dans un canevas, si le HTML dans un canevas n'est pas pris en charge, placez le contenu HTML au-dessus du canevas à l'aide de CSS.
Polyfill HTML-in-Canvas
Utilisez le script polyfill suivant pour imiter l'API HTML-in-Canvas dans les navigateurs qui ne la prennent pas en charge.
Installez ou intégrez la bibliothèque :
# Install npm install three-html-render# Embed <script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>Exécutez la méthode
installHtmlInCanvasPolyfill()pour traduire du code HTML dans Canvas.