@babylonjs/core 9.13.0 → 9.14.0

package/Materials/Textures/HTML/htmlInCanvasPolyfill.d.ts

@@ -0,0 +1,43 @@
+/** This module has no top-level side effects: it only declares the optional HTML-in-Canvas polyfill installer */
+/**
+ * Shape of the `three-html-render` polyfill module (only the parts this wrapper uses).
+ */
+export interface IHtmlInCanvasPolyfillModule {
+    /** Installs the WICG HTML-in-Canvas polyfill onto the relevant DOM prototypes. */
+    installHtmlInCanvasPolyfill?: (options?: {
+        force?: boolean;
+    }) => void;
+    /** Removes a previously installed polyfill. */
+    uninstallHtmlInCanvasPolyfill?: () => void;
+}
+/**
+ * Options for {@link InstallHtmlInCanvasPolyfill}.
+ */
+export interface IInstallHtmlInCanvasPolyfillOptions {
+    /** Install the polyfill even when the browser already supports the API natively (default false). */
+    force?: boolean;
+    /** Module specifier to lazily import the polyfill from (default `"three-html-render"`). */
+    moduleSpecifier?: string;
+    /** A pre-imported polyfill module to use instead of dynamically importing one. */
+    polyfillModule?: IHtmlInCanvasPolyfillModule;
+}
+/**
+ * Detects whether the browser supports the WICG HTML-in-Canvas API natively (or already has it installed).
+ * @returns true when an HTMLCanvasElement exposes `captureElementImage`
+ */
+export declare function IsHtmlInCanvasSupportedNatively(): boolean;
+/**
+ * Lazily installs the WICG HTML-in-Canvas polyfill (`three-html-render`) so that {@link HtmlTexture} and the
+ * interaction managers work in browsers that do not yet ship the native API.
+ *
+ * The polyfill is an optional dependency: it is imported on demand and never bundled into Babylon. When the
+ * browser already supports the API natively, this is a no-op unless `force` is set or the `?polyfillHIC` URL
+ * flag is present.
+ * @param options optional installation configuration
+ * @returns a promise that resolves to true when the polyfill was installed, false otherwise
+ */
+export declare function InstallHtmlInCanvasPolyfill(options?: IInstallHtmlInCanvasPolyfillOptions): Promise<boolean>;
+/**
+ * Removes a polyfill previously installed by {@link InstallHtmlInCanvasPolyfill}.
+ */
+export declare function UninstallHtmlInCanvasPolyfill(): void;

package/Materials/Textures/HTML/htmlInCanvasPolyfill.js

@@ -0,0 +1,64 @@
+/** This module has no top-level side effects: it only declares the optional HTML-in-Canvas polyfill installer */
+import { Logger } from "../../../Misc/logger.js";
+let _InstalledModule = null;
+/**
+ * Detects whether the browser supports the WICG HTML-in-Canvas API natively (or already has it installed).
+ * @returns true when an HTMLCanvasElement exposes `captureElementImage`
+ */
+export function IsHtmlInCanvasSupportedNatively() {
+    if (typeof document === "undefined") {
+        return false;
+    }
+    const canvas = document.createElement("canvas");
+    return typeof canvas.captureElementImage === "function";
+}
+/**
+ * Lazily installs the WICG HTML-in-Canvas polyfill (`three-html-render`) so that {@link HtmlTexture} and the
+ * interaction managers work in browsers that do not yet ship the native API.
+ *
+ * The polyfill is an optional dependency: it is imported on demand and never bundled into Babylon. When the
+ * browser already supports the API natively, this is a no-op unless `force` is set or the `?polyfillHIC` URL
+ * flag is present.
+ * @param options optional installation configuration
+ * @returns a promise that resolves to true when the polyfill was installed, false otherwise
+ */
+export async function InstallHtmlInCanvasPolyfill(options = {}) {
+    const force = options.force ?? _HasPolyfillUrlFlag();
+    if (!force && IsHtmlInCanvasSupportedNatively()) {
+        return false;
+    }
+    const module = options.polyfillModule ?? (await _ImportPolyfill(options.moduleSpecifier ?? "three-html-render"));
+    if (!module || typeof module.installHtmlInCanvasPolyfill !== "function") {
+        Logger.Warn("HTML-in-Canvas: the polyfill module does not expose installHtmlInCanvasPolyfill; nothing was installed.");
+        return false;
+    }
+    module.installHtmlInCanvasPolyfill(force ? { force: true } : undefined);
+    _InstalledModule = module;
+    return true;
+}
+/**
+ * Removes a polyfill previously installed by {@link InstallHtmlInCanvasPolyfill}.
+ */
+export function UninstallHtmlInCanvasPolyfill() {
+    if (_InstalledModule && typeof _InstalledModule.uninstallHtmlInCanvasPolyfill === "function") {
+        _InstalledModule.uninstallHtmlInCanvasPolyfill();
+    }
+    _InstalledModule = null;
+}
+async function _ImportPolyfill(specifier) {
+    try {
+        // The specifier is a variable so bundlers leave this as a runtime import and the optional package is
+        // not required to be installed at build time. The UMD/global build cannot resolve a bare module
+        // specifier, so this dynamic import is neutralized there (see rewriteDynamicExternalImportsPlugin);
+        // UMD consumers should pass `polyfillModule` instead.
+        return (await import(/* @vite-ignore */ /* webpackIgnore: true */ specifier));
+    }
+    catch {
+        Logger.Warn(`HTML-in-Canvas: could not load polyfill module "${specifier}". Install three-html-render or pass a polyfillModule.`);
+        return null;
+    }
+}
+function _HasPolyfillUrlFlag() {
+    return typeof window !== "undefined" && !!window.location && /[?&]polyfillHIC\b/i.test(window.location.search);
+}
+//# sourceMappingURL=htmlInCanvasPolyfill.js.map

package/Materials/Textures/HTML/htmlInCanvasPolyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlInCanvasPolyfill.js","sourceRoot":"","sources":["../../../../../../dev/core/src/Materials/Textures/HTML/htmlInCanvasPolyfill.ts"],"names":[],"mappings":"AAAA,iHAAiH;AAGjH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AA2B9C,IAAI,gBAAgB,GAA0C,IAAI,CAAC;AAEnE;;;GAGG;AACH,MAAM,UAAU,+BAA+B;IAC3C,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAA0D,CAAC;IACzG,OAAO,OAAO,MAAM,CAAC,mBAAmB,KAAK,UAAU,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,UAA+C,EAAE;IAC/F,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,EAAE,CAAC;IAErD,IAAI,CAAC,KAAK,IAAI,+BAA+B,EAAE,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,IAAI,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,eAAe,IAAI,mBAAmB,CAAC,CAAC,CAAC;IACjH,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,2BAA2B,KAAK,UAAU,EAAE,CAAC;QACtE,MAAM,CAAC,IAAI,CAAC,yGAAyG,CAAC,CAAC;QACvH,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,CAAC,2BAA2B,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACxE,gBAAgB,GAAG,MAAM,CAAC;IAC1B,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B;IACzC,IAAI,gBAAgB,IAAI,OAAO,gBAAgB,CAAC,6BAA6B,KAAK,UAAU,EAAE,CAAC;QAC3F,gBAAgB,CAAC,6BAA6B,EAAE,CAAC;IACrD,CAAC;IACD,gBAAgB,GAAG,IAAI,CAAC;AAC5B,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,SAAiB;IAC5C,IAAI,CAAC;QACD,qGAAqG;QACrG,gGAAgG;QAChG,oGAAoG;QACpG,sDAAsD;QACtD,OAAO,CAAC,MAAM,MAAM,CAAC,kBAAkB,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAgC,CAAC;IACjH,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,CAAC,IAAI,CAAC,mDAAmD,SAAS,wDAAwD,CAAC,CAAC;QAClI,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED,SAAS,mBAAmB;IACxB,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACnH,CAAC","sourcesContent":["/** This module has no top-level side effects: it only declares the optional HTML-in-Canvas polyfill installer */\n\nimport { type Nullable } from \"../../../types\";\nimport { Logger } from \"../../../Misc/logger\";\n\n// Attribution: the WICG HTML-in-Canvas polyfill is `three-html-render` by Palash Bansal (`repalash`),\n// MIT. It is consumed as an optional, lazily-imported dependency and is never bundled into Babylon.\n\n/**\n * Shape of the `three-html-render` polyfill module (only the parts this wrapper uses).\n */\nexport interface IHtmlInCanvasPolyfillModule {\n    /** Installs the WICG HTML-in-Canvas polyfill onto the relevant DOM prototypes. */\n    installHtmlInCanvasPolyfill?: (options?: { force?: boolean }) => void;\n    /** Removes a previously installed polyfill. */\n    uninstallHtmlInCanvasPolyfill?: () => void;\n}\n\n/**\n * Options for {@link InstallHtmlInCanvasPolyfill}.\n */\nexport interface IInstallHtmlInCanvasPolyfillOptions {\n    /** Install the polyfill even when the browser already supports the API natively (default false). */\n    force?: boolean;\n    /** Module specifier to lazily import the polyfill from (default `\"three-html-render\"`). */\n    moduleSpecifier?: string;\n    /** A pre-imported polyfill module to use instead of dynamically importing one. */\n    polyfillModule?: IHtmlInCanvasPolyfillModule;\n}\n\nlet _InstalledModule: Nullable<IHtmlInCanvasPolyfillModule> = null;\n\n/**\n * Detects whether the browser supports the WICG HTML-in-Canvas API natively (or already has it installed).\n * @returns true when an HTMLCanvasElement exposes `captureElementImage`\n */\nexport function IsHtmlInCanvasSupportedNatively(): boolean {\n    if (typeof document === \"undefined\") {\n        return false;\n    }\n    const canvas = document.createElement(\"canvas\") as HTMLCanvasElement & { captureElementImage?: unknown };\n    return typeof canvas.captureElementImage === \"function\";\n}\n\n/**\n * Lazily installs the WICG HTML-in-Canvas polyfill (`three-html-render`) so that {@link HtmlTexture} and the\n * interaction managers work in browsers that do not yet ship the native API.\n *\n * The polyfill is an optional dependency: it is imported on demand and never bundled into Babylon. When the\n * browser already supports the API natively, this is a no-op unless `force` is set or the `?polyfillHIC` URL\n * flag is present.\n * @param options optional installation configuration\n * @returns a promise that resolves to true when the polyfill was installed, false otherwise\n */\nexport async function InstallHtmlInCanvasPolyfill(options: IInstallHtmlInCanvasPolyfillOptions = {}): Promise<boolean> {\n    const force = options.force ?? _HasPolyfillUrlFlag();\n\n    if (!force && IsHtmlInCanvasSupportedNatively()) {\n        return false;\n    }\n\n    const module = options.polyfillModule ?? (await _ImportPolyfill(options.moduleSpecifier ?? \"three-html-render\"));\n    if (!module || typeof module.installHtmlInCanvasPolyfill !== \"function\") {\n        Logger.Warn(\"HTML-in-Canvas: the polyfill module does not expose installHtmlInCanvasPolyfill; nothing was installed.\");\n        return false;\n    }\n\n    module.installHtmlInCanvasPolyfill(force ? { force: true } : undefined);\n    _InstalledModule = module;\n    return true;\n}\n\n/**\n * Removes a polyfill previously installed by {@link InstallHtmlInCanvasPolyfill}.\n */\nexport function UninstallHtmlInCanvasPolyfill(): void {\n    if (_InstalledModule && typeof _InstalledModule.uninstallHtmlInCanvasPolyfill === \"function\") {\n        _InstalledModule.uninstallHtmlInCanvasPolyfill();\n    }\n    _InstalledModule = null;\n}\n\nasync function _ImportPolyfill(specifier: string): Promise<Nullable<IHtmlInCanvasPolyfillModule>> {\n    try {\n        // The specifier is a variable so bundlers leave this as a runtime import and the optional package is\n        // not required to be installed at build time. The UMD/global build cannot resolve a bare module\n        // specifier, so this dynamic import is neutralized there (see rewriteDynamicExternalImportsPlugin);\n        // UMD consumers should pass `polyfillModule` instead.\n        return (await import(/* @vite-ignore */ /* webpackIgnore: true */ specifier)) as IHtmlInCanvasPolyfillModule;\n    } catch {\n        Logger.Warn(`HTML-in-Canvas: could not load polyfill module \"${specifier}\". Install three-html-render or pass a polyfillModule.`);\n        return null;\n    }\n}\n\nfunction _HasPolyfillUrlFlag(): boolean {\n    return typeof window !== \"undefined\" && !!window.location && /[?&]polyfillHIC\\b/i.test(window.location.search);\n}\n"]}

package/Materials/Textures/HTML/htmlInteractionManager.d.ts

@@ -0,0 +1,69 @@
+import { type Scene } from "../../../scene.pure.js";
+import { type AbstractMesh } from "../../../Meshes/abstractMesh.pure.js";
+import { type HtmlTexture } from "./htmlTexture.js";
+/**
+ * Builds the CSS `transform` string that positions an overlay element over the projected face of a mesh.
+ *
+ * The transform is applied with `transform-origin: 0 0`. Reading right to left it centers the element on
+ * its own origin, scales and rotates it to match the projected face, then translates it to the projected
+ * center (in CSS pixels, top-left origin).
+ * @param centerX projected center X in CSS pixels
+ * @param centerY projected center Y in CSS pixels
+ * @param scaleX horizontal scale to apply to the element
+ * @param scaleY vertical scale to apply to the element
+ * @param rotation in-plane rotation in radians
+ * @param elementWidth element width in pixels
+ * @param elementHeight element height in pixels
+ * @returns the CSS transform string
+ */
+export declare function ComputeOverlayCssTransform(centerX: number, centerY: number, scaleX: number, scaleY: number, rotation: number, elementWidth: number, elementHeight: number): string;
+/**
+ * Options for {@link HtmlInteractionManager}.
+ */
+export interface IHtmlInteractionManagerOptions {
+    /** The DOM element to overlay (defaults to the texture's element). */
+    targetElement?: HTMLElement;
+    /** Whether the overlay element captures pointer events so the browser hit-tests it natively (default true). */
+    enablePointerEvents?: boolean;
+}
+/**
+ * Overlays the live HTML element of an {@link HtmlTexture} on top of the projected face of a planar mesh,
+ * so the browser hit-tests the real DOM element natively (enabling focus, text selection and form input).
+ *
+ * Each frame the mesh face is projected to screen space and the element is translated, scaled and rotated
+ * to match. This is best suited to planar, camera-facing surfaces. For arbitrary or curved meshes, use the
+ * UV-based {@link HtmlRaycastInteractionManager} instead.
+ *
+ * The overlay is screen-aligned (position, size and in-plane rotation); it does not apply a full
+ * perspective skew, so steeply oblique faces will not be perspective-correct.
+ */
+export declare class HtmlInteractionManager {
+    private readonly _scene;
+    private readonly _mesh;
+    private readonly _element;
+    private _observer;
+    private _previousTransform;
+    private readonly _viewport;
+    private readonly _center;
+    private readonly _xAxis;
+    private readonly _yAxis;
+    private readonly _projectedCenter;
+    private readonly _projectedX;
+    private readonly _projectedY;
+    private readonly _corner;
+    private _restoreInertOnDispose;
+    /**
+     * Creates an overlay interaction manager.
+     * @param scene the scene whose camera drives the projection
+     * @param texture the HTML texture whose element should be overlaid
+     * @param mesh the planar mesh displaying the texture
+     * @param options optional configuration
+     */
+    constructor(scene: Scene, texture: HtmlTexture, mesh: AbstractMesh, options?: IHtmlInteractionManagerOptions);
+    private _update;
+    private _setTransform;
+    /**
+     * Detaches the manager and stops updating the overlay.
+     */
+    dispose(): void;
+}

package/Materials/Textures/HTML/htmlInteractionManager.js

@@ -0,0 +1,130 @@
+import { Matrix, Vector3 } from "../../../Maths/math.vector.pure.js";
+import { Viewport } from "../../../Maths/math.viewport.js";
+// Attribution: the overlay-and-hit-test technique used here is prior art from `three-html-render`
+// (Palash Bansal, MIT), three.js' `InteractionManager`, and Jake Archibald's `curved-markup` demo.
+// The implementation below is a clean-room rewrite against Babylon.js' own projection APIs.
+/**
+ * Builds the CSS `transform` string that positions an overlay element over the projected face of a mesh.
+ *
+ * The transform is applied with `transform-origin: 0 0`. Reading right to left it centers the element on
+ * its own origin, scales and rotates it to match the projected face, then translates it to the projected
+ * center (in CSS pixels, top-left origin).
+ * @param centerX projected center X in CSS pixels
+ * @param centerY projected center Y in CSS pixels
+ * @param scaleX horizontal scale to apply to the element
+ * @param scaleY vertical scale to apply to the element
+ * @param rotation in-plane rotation in radians
+ * @param elementWidth element width in pixels
+ * @param elementHeight element height in pixels
+ * @returns the CSS transform string
+ */
+export function ComputeOverlayCssTransform(centerX, centerY, scaleX, scaleY, rotation, elementWidth, elementHeight) {
+    return `translate(${centerX}px, ${centerY}px) rotate(${rotation}rad) scale(${scaleX}, ${scaleY}) translate(${-elementWidth / 2}px, ${-elementHeight / 2}px)`;
+}
+/**
+ * Overlays the live HTML element of an {@link HtmlTexture} on top of the projected face of a planar mesh,
+ * so the browser hit-tests the real DOM element natively (enabling focus, text selection and form input).
+ *
+ * Each frame the mesh face is projected to screen space and the element is translated, scaled and rotated
+ * to match. This is best suited to planar, camera-facing surfaces. For arbitrary or curved meshes, use the
+ * UV-based {@link HtmlRaycastInteractionManager} instead.
+ *
+ * The overlay is screen-aligned (position, size and in-plane rotation); it does not apply a full
+ * perspective skew, so steeply oblique faces will not be perspective-correct.
+ */
+export class HtmlInteractionManager {
+    /**
+     * Creates an overlay interaction manager.
+     * @param scene the scene whose camera drives the projection
+     * @param texture the HTML texture whose element should be overlaid
+     * @param mesh the planar mesh displaying the texture
+     * @param options optional configuration
+     */
+    constructor(scene, texture, mesh, options = {}) {
+        this._previousTransform = "";
+        // Reused across frames to avoid per-frame allocations.
+        this._viewport = new Viewport(0, 0, 0, 0);
+        this._center = new Vector3();
+        this._xAxis = new Vector3();
+        this._yAxis = new Vector3();
+        this._projectedCenter = new Vector3();
+        this._projectedX = new Vector3();
+        this._projectedY = new Vector3();
+        this._corner = new Vector3();
+        this._restoreInertOnDispose = false;
+        this._scene = scene;
+        this._mesh = mesh;
+        this._element = options.targetElement ?? texture.element;
+        this._element.style.position = "absolute";
+        this._element.style.left = "0px";
+        this._element.style.top = "0px";
+        this._element.style.transformOrigin = "0 0";
+        this._element.style.pointerEvents = (options.enablePointerEvents ?? true) ? "auto" : "none";
+        // This manager relies on native browser hit testing of the element. HtmlTexture marks the element
+        // `inert` while hosting it inside the rendering canvas (so it does not steal input from the canvas);
+        // clear that here so native interaction works, and restore it on dispose.
+        this._restoreInertOnDispose = this._element.hasAttribute("inert");
+        if (this._restoreInertOnDispose) {
+            this._element.removeAttribute("inert");
+        }
+        this._observer = scene.onAfterRenderObservable.add(() => this._update());
+    }
+    _update() {
+        const camera = this._scene.activeCamera;
+        const engine = this._scene.getEngine();
+        if (!camera) {
+            return;
+        }
+        const boundingBox = this._mesh.getBoundingInfo().boundingBox;
+        const world = this._mesh.getWorldMatrix();
+        const extend = boundingBox.extendSize;
+        this._center.copyFrom(boundingBox.centerWorld);
+        // World-space half-axis directions of the mesh face.
+        Vector3.TransformNormalFromFloatsToRef(extend.x, 0, 0, world, this._xAxis);
+        Vector3.TransformNormalFromFloatsToRef(0, extend.y, 0, world, this._yAxis);
+        const transform = this._scene.getTransformMatrix();
+        camera.viewport.toGlobalToRef(engine.getRenderWidth(), engine.getRenderHeight(), this._viewport);
+        Vector3.ProjectToRef(this._center, Matrix.IdentityReadOnly, transform, this._viewport, this._projectedCenter);
+        this._center.addToRef(this._xAxis, this._corner);
+        Vector3.ProjectToRef(this._corner, Matrix.IdentityReadOnly, transform, this._viewport, this._projectedX);
+        this._center.addToRef(this._yAxis, this._corner);
+        Vector3.ProjectToRef(this._corner, Matrix.IdentityReadOnly, transform, this._viewport, this._projectedY);
+        // Hide the overlay when the face is behind the camera.
+        if (this._projectedCenter.z < 0 || this._projectedCenter.z > 1) {
+            this._setTransform("translate(-99999px, -99999px)");
+            return;
+        }
+        const dpr = engine.getHardwareScalingLevel();
+        const centerX = this._projectedCenter.x * dpr;
+        const centerY = this._projectedCenter.y * dpr;
+        const halfWidth = Math.hypot(this._projectedX.x - this._projectedCenter.x, this._projectedX.y - this._projectedCenter.y) * dpr;
+        const halfHeight = Math.hypot(this._projectedY.x - this._projectedCenter.x, this._projectedY.y - this._projectedCenter.y) * dpr;
+        const rotation = Math.atan2(this._projectedX.y - this._projectedCenter.y, this._projectedX.x - this._projectedCenter.x);
+        const elementWidth = this._element.offsetWidth || 1;
+        const elementHeight = this._element.offsetHeight || 1;
+        const scaleX = (2 * halfWidth) / elementWidth;
+        const scaleY = (2 * halfHeight) / elementHeight;
+        this._setTransform(ComputeOverlayCssTransform(centerX, centerY, scaleX, scaleY, rotation, elementWidth, elementHeight));
+    }
+    _setTransform(transform) {
+        if (transform === this._previousTransform) {
+            return;
+        }
+        this._previousTransform = transform;
+        this._element.style.transform = transform;
+    }
+    /**
+     * Detaches the manager and stops updating the overlay.
+     */
+    dispose() {
+        if (this._restoreInertOnDispose) {
+            this._element.setAttribute("inert", "");
+            this._restoreInertOnDispose = false;
+        }
+        if (this._observer) {
+            this._scene.onAfterRenderObservable.remove(this._observer);
+            this._observer = null;
+        }
+    }
+}
+//# sourceMappingURL=htmlInteractionManager.js.map

package/Materials/Textures/HTML/htmlInteractionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlInteractionManager.js","sourceRoot":"","sources":["../../../../../../dev/core/src/Materials/Textures/HTML/htmlInteractionManager.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Scene } from \"../../../scene.pure\";\nimport { type AbstractMesh } from \"../../../Meshes/abstractMesh.pure\";\nimport { type HtmlTexture } from \"./htmlTexture\";\nimport { type Observer } from \"../../../Misc/observable.pure\";\nimport { type Nullable } from \"../../../types\";\n\nimport { Matrix, Vector3 } from \"../../../Maths/math.vector.pure\";\nimport { Viewport } from \"../../../Maths/math.viewport\";\n\n// Attribution: the overlay-and-hit-test technique used here is prior art from `three-html-render`\n// (Palash Bansal, MIT), three.js' `InteractionManager`, and Jake Archibald's `curved-markup` demo.\n// The implementation below is a clean-room rewrite against Babylon.js' own projection APIs.\n\n/**\n * Builds the CSS `transform` string that positions an overlay element over the projected face of a mesh.\n *\n * The transform is applied with `transform-origin: 0 0`. Reading right to left it centers the element on\n * its own origin, scales and rotates it to match the projected face, then translates it to the projected\n * center (in CSS pixels, top-left origin).\n * @param centerX projected center X in CSS pixels\n * @param centerY projected center Y in CSS pixels\n * @param scaleX horizontal scale to apply to the element\n * @param scaleY vertical scale to apply to the element\n * @param rotation in-plane rotation in radians\n * @param elementWidth element width in pixels\n * @param elementHeight element height in pixels\n * @returns the CSS transform string\n */\nexport function ComputeOverlayCssTransform(\n    centerX: number,\n    centerY: number,\n    scaleX: number,\n    scaleY: number,\n    rotation: number,\n    elementWidth: number,\n    elementHeight: number\n): string {\n    return `translate(${centerX}px, ${centerY}px) rotate(${rotation}rad) scale(${scaleX}, ${scaleY}) translate(${-elementWidth / 2}px, ${-elementHeight / 2}px)`;\n}\n\n/**\n * Options for {@link HtmlInteractionManager}.\n */\nexport interface IHtmlInteractionManagerOptions {\n    /** The DOM element to overlay (defaults to the texture's element). */\n    targetElement?: HTMLElement;\n    /** Whether the overlay element captures pointer events so the browser hit-tests it natively (default true). */\n    enablePointerEvents?: boolean;\n}\n\n/**\n * Overlays the live HTML element of an {@link HtmlTexture} on top of the projected face of a planar mesh,\n * so the browser hit-tests the real DOM element natively (enabling focus, text selection and form input).\n *\n * Each frame the mesh face is projected to screen space and the element is translated, scaled and rotated\n * to match. This is best suited to planar, camera-facing surfaces. For arbitrary or curved meshes, use the\n * UV-based {@link HtmlRaycastInteractionManager} instead.\n *\n * The overlay is screen-aligned (position, size and in-plane rotation); it does not apply a full\n * perspective skew, so steeply oblique faces will not be perspective-correct.\n */\nexport class HtmlInteractionManager {\n    private readonly _scene: Scene;\n    private readonly _mesh: AbstractMesh;\n    private readonly _element: HTMLElement;\n    private _observer: Nullable<Observer<Scene>>;\n    private _previousTransform: string = \"\";\n\n    // Reused across frames to avoid per-frame allocations.\n    private readonly _viewport = new Viewport(0, 0, 0, 0);\n    private readonly _center = new Vector3();\n    private readonly _xAxis = new Vector3();\n    private readonly _yAxis = new Vector3();\n    private readonly _projectedCenter = new Vector3();\n    private readonly _projectedX = new Vector3();\n    private readonly _projectedY = new Vector3();\n    private readonly _corner = new Vector3();\n    private _restoreInertOnDispose: boolean = false;\n\n    /**\n     * Creates an overlay interaction manager.\n     * @param scene the scene whose camera drives the projection\n     * @param texture the HTML texture whose element should be overlaid\n     * @param mesh the planar mesh displaying the texture\n     * @param options optional configuration\n     */\n    constructor(scene: Scene, texture: HtmlTexture, mesh: AbstractMesh, options: IHtmlInteractionManagerOptions = {}) {\n        this._scene = scene;\n        this._mesh = mesh;\n        this._element = options.targetElement ?? texture.element;\n\n        this._element.style.position = \"absolute\";\n        this._element.style.left = \"0px\";\n        this._element.style.top = \"0px\";\n        this._element.style.transformOrigin = \"0 0\";\n        this._element.style.pointerEvents = (options.enablePointerEvents ?? true) ? \"auto\" : \"none\";\n\n        // This manager relies on native browser hit testing of the element. HtmlTexture marks the element\n        // `inert` while hosting it inside the rendering canvas (so it does not steal input from the canvas);\n        // clear that here so native interaction works, and restore it on dispose.\n        this._restoreInertOnDispose = this._element.hasAttribute(\"inert\");\n        if (this._restoreInertOnDispose) {\n            this._element.removeAttribute(\"inert\");\n        }\n\n        this._observer = scene.onAfterRenderObservable.add(() => this._update());\n    }\n\n    private _update(): void {\n        const camera = this._scene.activeCamera;\n        const engine = this._scene.getEngine();\n        if (!camera) {\n            return;\n        }\n\n        const boundingBox = this._mesh.getBoundingInfo().boundingBox;\n        const world = this._mesh.getWorldMatrix();\n        const extend = boundingBox.extendSize;\n\n        this._center.copyFrom(boundingBox.centerWorld);\n        // World-space half-axis directions of the mesh face.\n        Vector3.TransformNormalFromFloatsToRef(extend.x, 0, 0, world, this._xAxis);\n        Vector3.TransformNormalFromFloatsToRef(0, extend.y, 0, world, this._yAxis);\n\n        const transform = this._scene.getTransformMatrix();\n        camera.viewport.toGlobalToRef(engine.getRenderWidth(), engine.getRenderHeight(), this._viewport);\n\n        Vector3.ProjectToRef(this._center, Matrix.IdentityReadOnly, transform, this._viewport, this._projectedCenter);\n        this._center.addToRef(this._xAxis, this._corner);\n        Vector3.ProjectToRef(this._corner, Matrix.IdentityReadOnly, transform, this._viewport, this._projectedX);\n        this._center.addToRef(this._yAxis, this._corner);\n        Vector3.ProjectToRef(this._corner, Matrix.IdentityReadOnly, transform, this._viewport, this._projectedY);\n\n        // Hide the overlay when the face is behind the camera.\n        if (this._projectedCenter.z < 0 || this._projectedCenter.z > 1) {\n            this._setTransform(\"translate(-99999px, -99999px)\");\n            return;\n        }\n\n        const dpr = engine.getHardwareScalingLevel();\n        const centerX = this._projectedCenter.x * dpr;\n        const centerY = this._projectedCenter.y * dpr;\n\n        const halfWidth = Math.hypot(this._projectedX.x - this._projectedCenter.x, this._projectedX.y - this._projectedCenter.y) * dpr;\n        const halfHeight = Math.hypot(this._projectedY.x - this._projectedCenter.x, this._projectedY.y - this._projectedCenter.y) * dpr;\n        const rotation = Math.atan2(this._projectedX.y - this._projectedCenter.y, this._projectedX.x - this._projectedCenter.x);\n\n        const elementWidth = this._element.offsetWidth || 1;\n        const elementHeight = this._element.offsetHeight || 1;\n        const scaleX = (2 * halfWidth) / elementWidth;\n        const scaleY = (2 * halfHeight) / elementHeight;\n\n        this._setTransform(ComputeOverlayCssTransform(centerX, centerY, scaleX, scaleY, rotation, elementWidth, elementHeight));\n    }\n\n    private _setTransform(transform: string): void {\n        if (transform === this._previousTransform) {\n            return;\n        }\n        this._previousTransform = transform;\n        this._element.style.transform = transform;\n    }\n\n    /**\n     * Detaches the manager and stops updating the overlay.\n     */\n    public dispose(): void {\n        if (this._restoreInertOnDispose) {\n            this._element.setAttribute(\"inert\", \"\");\n            this._restoreInertOnDispose = false;\n        }\n        if (this._observer) {\n            this._scene.onAfterRenderObservable.remove(this._observer);\n            this._observer = null;\n        }\n    }\n}\n"]}

package/Materials/Textures/HTML/htmlRaycastInteractionManager.d.ts

@@ -0,0 +1,84 @@
+import { type Scene } from "../../../scene.pure.js";
+import { type AbstractMesh } from "../../../Meshes/abstractMesh.pure.js";
+import { type HtmlTexture } from "./htmlTexture.js";
+/**
+ * Maps a UV coordinate sampled from an {@link HtmlTexture} to a pixel position inside the source element.
+ *
+ * When `invertY` is true (the default, matching {@link HtmlTexture}'s default upload orientation) the V
+ * axis is flipped so that `v = 1` maps to the top of the element, matching the top-left origin used by
+ * DOM layout.
+ * @param u horizontal texture coordinate, normally in [0, 1]
+ * @param v vertical texture coordinate, normally in [0, 1]
+ * @param width element width in pixels
+ * @param height element height in pixels
+ * @param invertY whether the texture content is stored Y-inverted (default true)
+ * @returns the pixel position `{ x, y }` within the element
+ */
+export declare function GetElementPixelFromUv(u: number, v: number, width: number, height: number, invertY?: boolean): {
+    x: number;
+    y: number;
+};
+/**
+ * Options for {@link HtmlRaycastInteractionManager}.
+ */
+export interface IHtmlRaycastInteractionManagerOptions {
+    /** The DOM element that receives the forwarded pointer events (defaults to the texture's element). */
+    targetElement?: HTMLElement;
+    /** Whether hits on back-facing geometry are ignored (default true). */
+    backFaceCulling?: boolean;
+    /** Whether the texture content is stored Y-inverted, used when mapping UVs to element pixels (default true). */
+    invertY?: boolean;
+}
+/**
+ * Routes Babylon pointer events to a live HTML element rendered through an {@link HtmlTexture}.
+ *
+ * On every pointer event the scene is picked; when the configured mesh is hit, the picked UV is mapped to
+ * a pixel inside the source element and an equivalent DOM pointer (and mouse) event is dispatched there.
+ * This works for arbitrary meshes (planes, boxes, curved surfaces) because it relies on UV coordinates
+ * rather than a flat CSS overlay. For a perspective-correct overlay on planar surfaces, see
+ * {@link HtmlInteractionManager}.
+ */
+export declare class HtmlRaycastInteractionManager {
+    private readonly _scene;
+    private readonly _mesh;
+    private readonly _element;
+    private readonly _backFaceCulling;
+    private readonly _invertY;
+    private _observer;
+    private _downTarget;
+    private readonly _containHandler;
+    private readonly _rectCache;
+    private _rectCacheValid;
+    private readonly _invalidateRectCache;
+    private _resizeObserver;
+    private _mutationObserver;
+    /**
+     * Creates a raycast interaction manager.
+     * @param scene the scene to listen to for pointer events
+     * @param texture the HTML texture whose element should receive the forwarded events
+     * @param mesh the mesh displaying the texture; only hits on this mesh are forwarded
+     * @param options optional configuration
+     */
+    constructor(scene: Scene, texture: HtmlTexture, mesh: AbstractMesh, options?: IHtmlRaycastInteractionManagerOptions);
+    private _onPointer;
+    private _isBackFace;
+    private _dispatch;
+    /**
+     * Resolves the deepest descendant of the hosted element whose layout box contains the given client point.
+     * @param clientX horizontal client coordinate
+     * @param clientY vertical client coordinate
+     * @returns the deepest matching element, or the hosted element itself when no descendant matches
+     */
+    private _resolveTarget;
+    /**
+     * Returns the client rect of an element, served from a cache that is rebuilt only when layout may have
+     * changed (see the constructor). This keeps pointer routing free of per-event layout reads.
+     * @param element the element whose bounding rect is needed
+     * @returns the element's cached {@link DOMRect}
+     */
+    private _getRect;
+    /**
+     * Detaches the manager and stops forwarding pointer events.
+     */
+    dispose(): void;
+}