החלת הצללות של WebGL על תוכן HTML

תכונות אינטרנט: HTML ב-Canvas

הצללות ב-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" לרכיב ה-HTML‏ <canvas>.

  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 הם בפיקסלים של רשת ה-canvas (מאגר הגיבוי), אז צריך לעגל אותם כלפי מעלה באמצעות 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. מעבדים את תוכן ה-HTML למרקם בתוך גורם מטפל באירועים מסוג canvas.onpaint באמצעות השיטה texElementSubImage2D. צריך לפעול לפי הכללים הבאים:

    • אפשר להעלות רכיב רק אחרי שהוא צויר ב-canvas. אפשר להעלות אותו מהאירוע paint, או להתקשר למספר canvas.requestPaint() כדי לבקש אותו.
    • מעבירים את { width, height } בהגדרה. הוא גורם לעותק למלא את הטקסטורה שהוקצתה, בלי קשר לקנה המידה של ה-canvas.
    • אם הגודל השתנה, מקצים מחדש את הטקסטורה, כמו שמוצג בשלב 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 מעובד ב-canvas. ‫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, ל-canvas, בפיקסלים של CSS. הדפדפן צריך למפות את מרחב הקואורדינטות התלת-ממדי למרחב הקואורדינטות של ה-CSS באמצעות טרנספורמציה של אזור התצוגה. כדי לעשות את זה:

  • מנרמלים את רכיב ה-HTML. הגודל של רכיבי HTML נמדד בפיקסלים (לדוגמה, רוחב של 200 פיקסלים). לעומת זאת, ב-WebGL בדרך כלל מתייחסים לאובייקטים כאל "ריבועי יחידה", למשל, בטווח שבין 0.5- ל-0.5. אם לא תבצעו נרמול, כפתור בגודל 200 פיקסלים ייראה גדול פי 200. בשלב הזה גם הופכים את ציר ה-Y, כי ב-CSS, הכיוון למטה הוא חיובי, אבל ב-WebGL, הכיוון למעלה הוא חיובי.
  • ממירים את מטריצת ה-MVP של WebGL למטריצת DOM.
  • מיפוי לאזור התצוגה של אזור העריכה. השלב הזה הוא שלב "שינוי קנה המידה": הוא מותח את המתמטיקה של מרחב היחידה בחזרה כדי להתאים לממדי הפיקסלים של CSS של רכיב <canvas> במסך, והופך את ציר ה-Y בחזרה.

  • מחשבים את הטרנספורמציה הסופית. מכפילים את המטריצות לפי הסדר: Viewport * MVP * Normalization. שילוב של כל הטרנספורמציות האלה לטרנספורמציה סופית אחת יוצר "מפה" שאומרת לדפדפן בדיוק איפה רכיב ה-HTML צריך להיות כדי להתאים לשרטוט התלת-ממדי. הדפדפן מבצע את חלוקת הפרספקטיבה.

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

אחר כך מעבירים את הטרנספורמציה אל canvas.updateElementGeometry() בתור canvasTransform. הפעולה הזו מעבירה את רכיב ה-HTML כך שהוא יושב ישירות מעל הפיקסלים שעברו עיבוד. כך אפשר לוודא שכאשר משתמש לוחץ על לחצן או בוחר טקסט, הוא באמת לוחץ על רכיב ה-HTML האמיתי. הדפדפן משתמש בטרנספורמציה גם לגבולות הנגישות של הרכיב, למשל, לטבעות המיקוד של קורא המסך:

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

אפשר להשתמש באפשרויות הבאות כדי לשלוט בבדיקה של מיקום המצביע:

  • כל קריאה ל-updateElementGeometry() מעבירה את הרכיב לראש הסדר של בדיקת מיקום המצביע. צריך להעביר את { preserveHitTestOrder: true } כדי לשמור על המיקום שלו.
  • מפעילים את canvas.clearElementGeometry(element) כדי להסיר רכיב מבדיקת מיקום המצביע, למשל כשמסתירים אותו.
  • מעבירים את { canvasClip }, שהוא DOMRectInit במרחב הקואורדינטות של canvasTransform, כדי להגביל את האזור שניתן לבדוק, למשל, כשמצויר רק חלק מהרכיב.

קוד לדוגמה

<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, צריך לבדוק אם הדפדפן תומך בו.
  • חובה: תמיד צריך להוסיף את המאפיין content="drawable" לרכיב <canvas>.
  • חובה: תמיד צריך להוסיף את המאפיין drawable לצאצאים הישירים של אזור העריכה.
  • חובה: מוסיפים את המאפיין drawable לכל רכיב שרוצים שיהיה אפשר לצייר בנפרד מרכיבי ההורה שלו.
  • חובה: צריך להשתמש בגורם מטפל באירועים onpaint כדי להציג את תוכן ה-HTML ב-canvas.
  • חובה: מקצים מראש את מאגר הטקסטורות באמצעות texImage2D() פעם אחת (כשהוא מאותחל או כשגודל הרכיב משתנה). מקצים מחדש את הטקסטורה רק כשהגודל משתנה, ומגדירים את TEXTURE_MIN_FILTER ל-LINEAR.
  • חובה: צריך להשתמש ב-method‏ texElementSubImage2D כדי לעבד את תוכן ה-HTML למרקם שמוקצה מראש באמצעות texImage2D(), בגודל מ-captureElementImage().
  • חובה: מסנכרנים את הגיאומטריה של רכיב ה-HTML עם התוכן שעבר רינדור באמצעות קריאה ל-canvas.updateElementGeometry(element, { canvasTransform }).
  • חובה: צריך להשתמש ב-ResizeObserver כדי לבדוק את גודל המסך ולעדכן את גודל אזור העריכה כך שיתאים לפיקסלים של המכשיר.
  • אל תטמיעו תוכן ממקורות שונים ב-Canvas, כי אין תמיכה בכך.
  • אל תפעילו את ResizeObserver בתוך הגורם המטפל באירועים onpaint, כי זה עלול לגרום לדליפות זיכרון.

אסטרטגיות חלופיות

ה-API של HTML-in-Canvas לא נתמך כרגע בכל הדפדפנים המודרניים, ולכן בדרך כלל נדרשת אסטרטגיית גיבוי.

עם זאת, לאור היתרונות של ה-API הזה בשיפור הביצועים, כדאי להשתמש ב-HTML-in-Canvas אם הדפדפן תומך בו.

אסטרטגיית ברירת המחדל תלויה בתרחיש לדוגמה. לדוגמה, אם אתם רוצים להציג תוכן HTML אינטראקטיבי ב-canvas, אבל אין תמיכה ב-HTML-in-Canvas, אתם יכולים להציב את תוכן ה-HTML מעל ה-canvas באמצעות CSS.

HTML-in-Canvas polyfill

כדי לדמות את ה-API של HTML-in-Canvas בדפדפנים שלא תומכים בו, צריך להשתמש בסקריפט ה-polyfill הבא.

  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.