@animech-public/playcanvas
Version:
PlayCanvas WebGL game engine
92 lines (91 loc) • 2.99 kB
TypeScript
/**
* 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', function (evt) {
* evt.preventDefault();
* });
* ```
*
* @category XR
*/
export class XrDomOverlay {
/**
* Create a new XrDomOverlay instance.
*
* @param {import('./xr-manager.js').XrManager} manager - WebXR Manager.
* @ignore
*/
constructor(manager: import("./xr-manager.js").XrManager);
/**
* @type {import('./xr-manager.js').XrManager}
* @private
*/
private _manager;
/**
* @type {boolean}
* @private
*/
private _supported;
/**
* @type {Element|null}
* @private
*/
private _root;
/**
* True if DOM Overlay is supported.
*
* @type {boolean}
*/
get supported(): boolean;
/**
* 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(): boolean;
/**
* State of the DOM Overlay, which defines how the root DOM element is rendered. Possible
* options:
*
* - screen - indicates that the DOM element is covering 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 {string|null}
*/
get state(): string | null;
/**
* Sets the DOM element to be used as the root for DOM Overlay. Can be changed only when 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: Element | null);
/**
* Gets the DOM element to be used as the root for DOM Overlay.
*
* @type {Element|null}
*/
get root(): Element | null;
}