playcanvas/build/playcanvas.dbg/src/framework/xr/xr-dom-overlay.js

PlayCanvas WebGL game engine

import { platform } from '../../core/platform.js';

/**
 * @import { XrManager } from './xr-manager.js'
 */ /**
 * DOM Overlay provides the ability to use DOM elements as an overlay in a WebXR AR session. It
 * requires that the root DOM element is provided for session start. That way, input source
 * `select` events are first tested against DOM Elements and then propagated down to the XR
 * Session. If this propagation is not desirable, use the `beforexrselect` event on a DOM element
 * and the `preventDefault` function to stop propagation.
 *
 * ```javascript
 * app.xr.domOverlay.root = element;
 * app.xr.start(camera, pc.XRTYPE_AR, pc.XRSPACE_LOCALFLOOR);
 * ```
 *
 * ```javascript
 * // Disable input source firing `select` event when some descendant element of DOM overlay root
 * // is touched/clicked. This is useful when the user interacts with UI elements and there should
 * // not be `select` events behind UI.
 * someElement.addEventListener('beforexrselect', (evt) => {
 *     evt.preventDefault();
 * });
 * ```
 *
 * @category XR
 */ class XrDomOverlay {
    /**
     * Create a new XrDomOverlay instance.
     *
     * @param {XrManager} manager - WebXR Manager.
     * @ignore
     */ constructor(manager){
        /**
     * @type {boolean}
     * @private
     */ this._supported = platform.browser && !!window.XRDOMOverlayState;
        /**
     * @type {Element|null}
     * @private
     */ this._root = null;
        this._manager = manager;
    }
    /**
     * True if DOM Overlay is supported.
     *
     * @type {boolean}
     */ get supported() {
        return this._supported;
    }
    /**
     * True if DOM Overlay is available. This information becomes available only when the session has
     * started and a valid root DOM element has been provided.
     *
     * @type {boolean}
     */ get available() {
        return this._supported && this._manager.active && this._manager._session.domOverlayState !== null;
    }
    /**
     * State of the DOM Overlay, which defines how the root DOM element is rendered. Can be:
     *
     * - `screen` - indicates that the DOM element is covering the whole physical screen, matching
     * XR viewports.
     * - `floating` - indicates that the underlying platform renders the DOM element as floating in
     * space, which can move during the WebXR session or allow the application to move the element.
     * - `head-locked` - indicates that the DOM element follows the user's head movement
     * consistently, appearing similar to a helmet heads-up display.
     *
     * @type {"screen"|"floating"|"head-locked"|null}
     */ get state() {
        if (!this._supported || !this._manager.active || !this._manager._session.domOverlayState) {
            return null;
        }
        return this._manager._session.domOverlayState.type;
    }
    /**
     * Sets the DOM element to be used as the root for DOM Overlay. Can be changed only when the XR
     * session is not running.
     *
     * @type {Element|null}
     * @example
     * app.xr.domOverlay.root = element;
     * app.xr.start(camera, pc.XRTYPE_AR, pc.XRSPACE_LOCALFLOOR);
     */ set root(value) {
        if (!this._supported || this._manager.active) {
            return;
        }
        this._root = value;
    }
    /**
     * Gets the DOM element to be used as the root for DOM Overlay.
     *
     * @type {Element|null}
     */ get root() {
        return this._root;
    }
}

export { XrDomOverlay };