WebGL-Shader auf HTML-Inhalte anwenden

WebGL-Shader bieten leistungsstarke GPU-beschleunigte visuelle Effekte und ermöglichen erweiterte Funktionen wie dynamische Wellenverzerrungen, Beleuchtungsmodelle, Farbkorrekturen und benutzerdefinierte Vertex-Transformationen. Mit der HTML-in-Canvas API können Entwickler WebGL-Texturen auf HTML-Inhalte anwenden. So können leistungsstarke Fragment- und Vertex-Shader nativ auf vollständig interaktive UI-Komponenten wie Schaltflächen, Eingabefelder und Rich Text angewendet werden, während die native Barrierefreiheit, Textauswahl und DOM-Ereignisverarbeitung beibehalten werden.

Implementierung

1. Prüfen Sie, ob HTML-in-Canvas im Browser unterstützt wird:

   if ('content' in HTMLCanvasElement.prototype) {
     // Use HTML in Canvas API
   } else {
     // Use fallback strategy
   }
   

2. Fügen Sie dem HTML-Element <canvas> das Attribut content="drawable" hinzu.

3. Platziere deinen HTML-Inhalt innerhalb des <canvas>-Elements und füge jedem Element, das du zeichnest, das Attribut drawable hinzu. Ein Element mit drawable erfasst seinen Unterbaum, mit Ausnahme von verschachtelten Nachfolgerelementen, die ebenfalls drawable sind.

   <canvas id="canvas" content="drawable">
     <div id="html-content" drawable></div>
   </canvas>
   

4. Skalieren Sie das Canvas-Raster so, dass es dem Skalierungsfaktor des Geräts entspricht, um Unschärfe zu vermeiden:

   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);
   

5. Weisen Sie zuerst den Texturspeicher mit der Methode texImage2D vorab zu. In den Snippets in diesem Leitfaden wird ein WebGL 2-Kontext (canvas.getContext("webgl2")) verwendet.

Weisen Sie zuerst Texturspeicher zu, indem Sie texImage2D() mit null anstelle von Pixeldaten aufrufen. Dadurch wird GPU-Speicher der angegebenen Größe und des angegebenen Formats reserviert, ohne dass Pixel hochgeladen werden. Gehen Sie dabei so vor:

• Größe der Textur von canvas.captureElementImage(element) festlegen. Die Werte für width und height werden in Pixeln des Zeichenflächenrasters (Backing Store) angegeben. Runden Sie sie daher mit Math.ceil() auf. captureElementImage() löst einen Fehler aus, wenn das Element noch keinen Paint-Eintrag hat: Rufen Sie requestPaint() auf und versuchen Sie es beim nächsten paint-Ereignis noch einmal.
• Weisen Sie Ebene 0 nur beim ersten Upload oder bei einer Größenänderung zu, da die Textur durch die Neuzuweisung gelöscht wird. Veränderlichen Speicher verwenden: Die Größe von unveränderlichem texStorage2D()-Speicher kann nicht geändert werden, wenn sich die Größe des Elements ändert.

// 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 };

1. Rendern Sie den HTML-Inhalt in einem canvas.onpaint-Event-Handler mit der Methode texElementSubImage2D in die Textur. Gehen Sie dabei so vor:

   • Ein Element kann erst hochgeladen werden, nachdem es auf dem Canvas dargestellt wurde. Laden Sie die Datei aus dem paint-Ereignis hoch und rufen Sie canvas.requestPaint() auf, um eine Datei anzufordern.
   • Übergeben Sie { width, height } in der Konfiguration. Die Kopie füllt die zugewiesene Textur aus, unabhängig davon, wie der Canvas skaliert wird.
   • Weisen Sie die Textur neu zu, wenn sich die Größe geändert hat, wie in Schritt 5 gezeigt.

// 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);
  }
};

Wenn Sie eine requestAnimationFrame-Schleife zum Rendern der Szene verwenden, rufen Sie canvas.requestPaint() innerhalb der Schleife auf, damit der HTML-Inhalt auf dem Canvas gerendert wird. event.changedElements listet die Elemente auf, deren Rendering sich geändert hat. Laden Sie die Textur nur dann noch einmal hoch, wenn die untergeordneten HTML-Elemente aktualisiert wurden:

  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
  };

1. Synchronisieren Sie die Elementgeometrie.

Berechnen Sie eine DOMMatrix, die die Rahmenbox des Elements in CSS-Pixeln dem Canvas in CSS-Pixeln zuordnet. Der Browser muss den 3D-Koordinatenraum mithilfe einer Darstellungsbereichstransformation in den CSS-Koordinatenraum umwandeln. Gehen Sie dazu so vor:

• Normalisieren Sie das HTML-Element. Die Größe von HTML-Elementen wird in Pixeln angegeben (z. B. 200 px breit). WebGL behandelt Objekte jedoch normalerweise als „Einheitsquadrate“, z.B.im Bereich von -0,5 bis 0,5. Wenn Sie die Werte nicht normalisieren, wird die 200 Pixel große Schaltfläche 200-mal größer dargestellt. In diesem Schritt wird auch die Y-Achse umgedreht, da in CSS nach unten positiv ist, in WebGL jedoch nach oben.
• Konvertieren Sie die WebGL-MVP-Matrix in eine DOM-Matrix.
• Ordnen Sie die Daten dem Darstellungsbereich des Canvas zu. Dieser Schritt ist die „Neuskalierungsphase“: Die mathematischen Werte des Einheitsraums werden wieder so gestreckt, dass sie den CSS-Pixelabmessungen des <canvas>-Elements auf dem Bildschirm entsprechen, und die Y-Achse wird wieder umgedreht.

• Berechnen Sie die endgültige Transformation. Multiplizieren Sie die Matrizen in der folgenden Reihenfolge: Darstellungsbereich * MVP * Normalisierung. Wenn Sie sie zu einer endgültigen Transformation kombinieren, entsteht eine „Karte“, die dem Browser genau mitteilt, wo sich das HTML-Element befinden soll, damit es mit der 3D-Zeichnung übereinstimmt. Der Browser führt die perspektivische Teilung durch.

  // 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);
  }
  

Übergeben Sie dann die Transformation als canvasTransform an canvas.updateElementGeometry(). Dadurch wird das HTML-Element direkt über den gerenderten Pixeln platziert. So wird sichergestellt, dass Nutzer, die auf eine Schaltfläche klicken oder Text auswählen, tatsächlich das echte HTML-Element treffen. Der Browser verwendet die Transformation auch für die Grenzen der Barrierefreiheit des Elements, z. B. für Fokusringe von Screenreadern:

  canvas.updateElementGeometry(targetHTMLElement, {
    canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
  });

Mit diesen Optionen können Sie die Trefferprüfung steuern:

• Mit jedem updateElementGeometry()-Aufruf wird das Element an den Anfang der Trefferprüfungsreihenfolge verschoben. Karte/Ticket „{ preserveHitTestOrder: true }“ behält die Position.
• Rufen Sie canvas.clearElementGeometry(element) auf, um ein Element aus der Trefferprüfung zu entfernen, z. B. wenn Sie es ausblenden.
• Übergeben Sie { canvasClip }, ein DOMRectInit im Koordinatenbereich von canvasTransform, um den Bereich für den Treffertest einzuschränken, z. B. wenn nur ein Teil des Elements gezeichnet wird.

Beispielcode

<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>

Best Practices

• OBLIGATORISCH: Prüfen Sie die Browserunterstützung für die HTML-in-Canvas API, bevor Sie sie verwenden.
• OBLIGATORISCH: Fügen Sie dem <canvas>-Element immer das Attribut content="drawable" hinzu.
• OBLIGATORISCH: Fügen Sie den direkt untergeordneten Elementen des Canvas IMMER das Attribut drawable hinzu.
• ERFORDERLICH: Fügen Sie das Attribut drawable jedem Element hinzu, das unabhängig von seinen übergeordneten Elementen gezeichnet werden soll.
• OBLIGATORISCH: Verwenden Sie einen onpaint-Event-Handler, um den HTML-Inhalt auf dem Canvas zu rendern.
• OBLIGATORISCH: Weisen Sie dem Texturpuffer einmalig mit texImage2D() Speicher zu (bei der Initialisierung oder wenn sich die Elementgröße ändert). Weisen Sie die Textur nur dann neu zu, wenn sich die Größe ändert, und setzen Sie TEXTURE_MIN_FILTER auf LINEAR.
• OBLIGATORISCH: Verwenden Sie die Methode texElementSubImage2D, um den HTML-Inhalt in einer Textur zu rendern, die Sie mit texImage2D() vorab zuweisen und deren Größe Sie mit captureElementImage() festlegen.
• ERFORDERLICH: Synchronisieren Sie die Geometrie des HTML-Elements mit dem gerenderten Inhalt, indem Sie canvas.updateElementGeometry(element, { canvasTransform }) aufrufen.
• OBLIGATORISCH: Verwenden Sie ResizeObserver, um die Bildschirmgröße zu beobachten und die Canvas-Größe an die Gerätepixel anzupassen.
• Betten Sie KEINE ursprungsübergreifenden Inhalte in einen Canvas ein, da dies nicht unterstützt wird.
• Initialisieren Sie ResizeObserver NICHT im onpaint-Event-Handler, da dies zu Speicherlecks führen kann.

Fallback-Strategien

Die HTML-in-Canvas API wird derzeit nicht in allen modernen Browsern unterstützt. Daher ist in der Regel eine Fallback-Strategie erforderlich.

Aufgrund der verbesserten Leistung dieser API sollte HTML-in-Canvas jedoch verwendet werden, wenn der Browser dies unterstützt.

Die Fallback-Strategie hängt vom Anwendungsfall ab. Wenn HTML-in-Canvas beispielsweise nicht unterstützt wird, platzieren Sie den HTML-Inhalt mithilfe von CSS über dem Canvas.

HTML-in-Canvas-Polyfill

Verwenden Sie das folgende Polyfill-Skript, um die HTML-in-Canvas API in Browsern zu simulieren, die sie nicht unterstützen.

1. Installieren oder binden Sie die Bibliothek ein:

   # Install
   npm install three-html-render
   

   # Embed
   <script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>
   

2. Führen Sie die Methode installHtmlInCanvasPolyfill() aus, um HTML-in-Canvas zu übersetzen.