将 WebGL 着色器应用于 HTML 内容

Web 功能： 画布中的 HTML

WebGL 着色器提供强大的 GPU 加速视觉效果，可实现动态波纹扭曲、光照模型、颜色分级和自定义顶点转换等高级功能。借助 HTML-in-Canvas API，开发者可以将 WebGL 纹理应用于 HTML 内容。这样一来，您就可以将高性能片段和顶点着色器原生应用于完全交互式的界面组件（例如按钮、输入字段和富文本），同时保留原生无障碍功能、文本选择和 DOM 事件处理。

如何实现

  1. 检查浏览器是否支持 HTML-in-Canvas：

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

  2. 将 content="drawable" 属性添加到 <canvas> HTML 元素中。

  3. 将 HTML 内容放入 <canvas> 元素中，并为您绘制的每个元素添加 drawable 属性。具有 drawable 的元素会捕获其子树，但同样具有 drawable 的嵌套后代除外。

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

  4. 缩放画布网格以匹配设备缩放比例，从而防止模糊：

    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. 首先使用 texImage2D 方法预分配纹理后备。本指南中的代码段使用 WebGL 2 上下文 (canvas.getContext("webgl2"))。

首先，调用 texImage2D() 并传入 null（而非像素数据）来分配纹理存储空间，这会预留给定大小和格式的 GPU 内存，而不会上传任何像素。遵循以下规则：

  • 从 canvas.captureElementImage(element) 调整纹理大小。其 width 和 height 采用画布网格（后备存储区）像素，因此请使用 Math.ceil() 将其向上舍入。如果元素还没有绘制记录，captureElementImage() 会抛出异常：调用 requestPaint()，并在下一个 paint 事件中重试。
  • 仅在首次上传时或大小发生变化时分配级别 0，因为重新分配会清除纹理。使用可变存储：当元素大小发生变化时，不可变 texStorage2D() 存储无法调整大小。
// 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. 使用 texElementSubImage2D 方法在 canvas.onpaint 事件处理脚本中将 HTML 内容渲染到纹理。遵循以下规则：

    • 只有在画布绘制元素后，才能上传该元素。从 paint 事件上传，并调用 canvas.requestPaint() 请求一个。
    • 在配置中传递 { width, height }。无论画布如何缩放，它都会使副本填满分配的纹理。
    • 如果大小发生变化，请重新分配纹理，如第 5 步所示。
// 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);
  }
};

使用 requestAnimationFrame 循环渲染场景时，请在循环内调用 canvas.requestPaint()，以确保 HTML 内容渲染到画布。event.changedElements 列出了呈现方式发生变化的元素。请确保仅在后代 HTML 元素有更新时才重新上传纹理：

  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. 同步元素几何图形。

计算一个 DOMMatrix，用于将元素的边框（以 CSS 像素为单位）映射到画布（以 CSS 像素为单位）。浏览器需要使用视口转换，从 3D 坐标空间映射到 CSS 坐标空间。为此，请执行以下操作：

  • 对 HTML 元素进行标准化。HTML 元素的大小以像素为单位（例如，宽度为 200 像素）。不过，WebGL 通常会将对象视为“单位正方形”，例如，范围从 -0.5 到 0.5。如果不进行归一化，200 像素的按钮看起来会大 200 倍。此步骤还会翻转 Y 轴，因为在 CSS 中，向下为正，但在 WebGL 中，向上为正。
  • 将 WebGL MVP 矩阵转换为 DOM 矩阵。
  • 映射到画布视口。此步骤是“重新缩放”阶段：它会将该单位空间数学运算结果重新拉伸，以匹配屏幕上 <canvas> 元素的 CSS 像素尺寸，并将 Y 轴翻转回来。

  • 计算最终转换。按顺序将矩阵相乘：视口 * MVP * 归一化。将这些转换合并为一个最终转换，即可生成一个“映射”，告诉浏览器该 HTML 元素应位于何处，以便与 3D 绘图对齐。浏览器会执行透视除法。

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

然后，将转换作为 canvasTransform 传递给 canvas.updateElementGeometry()。这会将 HTML 元素移动到其渲染像素的正上方。这样可以确保当用户点击按钮或选择文本时，他们实际上点击的是真实的 HTML 元素。浏览器还会将该转换用于元素的无障碍边界，例如屏幕阅读器焦点环：

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

使用以下选项可控制点击测试：

  • 每次调用 updateElementGeometry() 都会将元素移至点击测试顺序的顶部。{ preserveHitTestOrder: true } 保持其位置。
  • 调用 canvas.clearElementGeometry(element) 可从点击测试中移除某个元素，例如在您隐藏该元素时。
  • 传递 { canvasClip }（canvasTransform 坐标空间中的 DOMRectInit），以限制可进行点击测试的区域，例如，仅绘制元素的一部分时。

示例代码

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

最佳做法

  • 强制要求：在使用 HTML-in-Canvas API 之前，请先检查浏览器是否支持该 API。
  • 强制性要求：始终向 <canvas> 元素添加 content="drawable" 属性。
  • 强制性要求：务必将 drawable 属性添加到画布的直接子级。
  • 强制性：向您希望能够独立于其父元素进行绘制的每个元素添加 drawable 属性。
  • 强制性要求：使用 onpaint 事件处理脚本将 HTML 内容呈现到画布上。
  • 强制性：使用 texImage2D() 预分配纹理缓冲区一次（在初始化时或元素大小发生变化时）。仅在大小发生变化时重新分配纹理，并将 TEXTURE_MIN_FILTER 设置为 LINEAR。
  • 强制性：使用 texElementSubImage2D 方法将 HTML 内容渲染到您使用 texImage2D() 预分配的纹理中，纹理大小由 captureElementImage() 确定。
  • 强制性：通过调用 canvas.updateElementGeometry(element, { canvasTransform })，将 HTML 元素的几何图形与呈现的内容同步。
  • 强制要求：使用 ResizeObserver 观察屏幕尺寸，并更新画布尺寸以匹配设备像素。
  • 请勿在画布中嵌入跨域内容，因为系统不支持这样做。
  • 请勿在 onpaint 事件处理脚本中初始化 ResizeObserver，因为这可能会导致内存泄漏。

后备策略

目前，并非所有现代浏览器都支持 HTML-in-Canvas API，因此通常需要采用后备策略。

不过，鉴于此 API 带来的性能提升，如果浏览器支持 HTML-in-Canvas，则应使用该 API。

后备策略取决于用例。例如，对于画布中的交互式 HTML 内容，如果不支持 HTML-in-Canvas，请使用 CSS 将 HTML 内容放置在画布顶部。

HTML-in-Canvas polyfill

在不支持 HTML-in-Canvas API 的浏览器中，请使用以下 polyfill 脚本来模拟该 API。

  1. 安装或嵌入库：

    # Install
npm install three-html-render

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

  2. 运行 installHtmlInCanvasPolyfill() 方法以翻译 HTML-in-Canvas。