Class XrManager

Manage and update XR session and its states.

Hierarchy (View Summary)

Properties

anchors domOverlay hitTest imageTracking input lightEstimation meshDetection planeDetection views

Accessors

active camera fixedFoveation framebufferScaleFactor frameRate session spaceType supported supportedFrameRates type

Methods

end fire hasEvent initiateRoomCapture isAvailable off on once start updateTargetFrameRate

Events

EVENT_AVAILABLE EVENT_END EVENT_ERROR EVENT_START EVENT_UPDATE

Properties

anchors

anchors: XrAnchors

Provides access to Anchors.

domOverlay

domOverlay: XrDomOverlay

Provides access to DOM overlay capabilities.

hitTest

hitTest: XrHitTest

Provides the ability to perform hit tests on the representation of real world geometry of the underlying AR system.

imageTracking

imageTracking: XrImageTracking

Provides access to image tracking capabilities.

input

input: XrInput

Provides access to Input Sources.

lightEstimation

lightEstimation: XrLightEstimation

Provides access to light estimation capabilities.

meshDetection

meshDetection: XrMeshDetection

Provides access to mesh detection capabilities.

planeDetection

planeDetection: XrPlaneDetection

Provides access to plane detection capabilities.

views

views: XrViews

Provides access to views and their capabilities.

Accessors

active

camera

fixedFoveation

  • get fixedFoveation(): number

  • Current fixed foveation level, which is between 0 and 1. 0 - no forveation, and 1 - highest foveation. If fixed foveation is not supported, this value returns null.

    Returns number

  • set fixedFoveation(value: number): void

  • Set fixed foveation to the value between 0 and 1. Where 0 - no foveation, and 1 - highest foveation. It only can be set during an active XR session. Fixed foveation will reduce the resolution of the back buffer at the edges of the sceen, which can improve rendering performance.

    Parameters

    • value: number

    Returns void

framebufferScaleFactor

frameRate

session

spaceType

supported

supportedFrameRates

type

Methods

end

  • end(callback?: XrErrorCallback): void

  • Attempts to end XR session and optionally fires callback when session is ended or failed to end.

    Parameters

    • Optionalcallback: XrErrorCallback

      Optional callback function called once session is started. The callback has one argument Error - it is null if successfully started XR session.

    Returns void

    Example

    app.keyboard.on('keydown', function (evt) {
        if (evt.key === pc.KEY_ESCAPE && app.xr.active) {
            app.xr.end();
        }
    });

fire

  • fire(
        name: string,
        arg1?: any,
        arg2?: any,
        arg3?: any,
        arg4?: any,
        arg5?: any,
        arg6?: any,
        arg7?: any,
        arg8?: any,
    ): EventHandler

  • Fire an event, all additional arguments are passed on to the event listener.

    Parameters

    • name: string

      Name of event to fire.

    • Optionalarg1: any

      First argument that is passed to the event handler.

    • Optionalarg2: any

      Second argument that is passed to the event handler.

    • Optionalarg3: any

      Third argument that is passed to the event handler.

    • Optionalarg4: any

      Fourth argument that is passed to the event handler.

    • Optionalarg5: any

      Fifth argument that is passed to the event handler.

    • Optionalarg6: any

      Sixth argument that is passed to the event handler.

    • Optionalarg7: any

      Seventh argument that is passed to the event handler.

    • Optionalarg8: any

      Eighth argument that is passed to the event handler.

    Returns EventHandler

    Self for chaining.

    Example

    obj.fire('test', 'This is the message');

hasEvent

  • hasEvent(name: string): boolean

  • Test if there are any handlers bound to an event name.

    Parameters

    • name: string

      The name of the event to test.

    Returns boolean

    True if the object has handlers bound to the specified event name.

    Example

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

initiateRoomCapture

  • initiateRoomCapture(callback: XrRoomCaptureCallback): void

  • Initiate manual room capture. If the underlying XR system supports manual capture of the room, it will start the capturing process, which can affect plane and mesh detection, and improve hit-test quality against real-world geometry.

    Parameters

    Returns void

    Example

    this.app.xr.initiateRoomCapture((err) => {
        if (err) {
            // capture failed
            return;
        }
        // capture was successful
    });

isAvailable

  • isAvailable(type: string): boolean

  • Check if specific type of session is available.

    Parameters

    • type: string

      Session type. Can be one of the following:

      • XRTYPE_INLINE: Inline - always available type of session. It has limited features availability and is rendered into HTML element.
      • XRTYPE_VR: Immersive VR - session that provides exclusive access to VR device with best available tracking features.
      • XRTYPE_AR: Immersive AR - session that provides exclusive access to VR/AR device that is intended to be blended with real-world environment.

    Returns boolean

    True if specified session type is available.

    Example

    if (app.xr.isAvailable(pc.XRTYPE_VR)) {
        // VR is available
    }

off

  • off(name?: string, callback?: HandleEventCallback, scope?: object): EventHandler

  • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

    Parameters

    • Optionalname: string

      Name of the event to unbind.

    • Optionalcallback: HandleEventCallback

      Function to be unbound.

    • Optionalscope: object

      Scope that was used as the this when the event is fired.

    Returns EventHandler

    Self for chaining.

    Example

    const handler = function () {
    };
    obj.on('test', handler);

    obj.off(); // Removes all events
    obj.off('test'); // Removes all events called 'test'
    obj.off('test', handler); // Removes all handler functions, called 'test'
    obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

on

  • on(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • Attach an event handler to an event.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    Can be used for removing event in the future.

    Example

    obj.on('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Example

    const evt = obj.on('test', function (a, b) {
        console.log(a + b);
    });
    // some time later
    evt.off();

once

  • once(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • Attach an event handler to an event. This handler will be removed after being fired once.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    • can be used for removing event in the future.

    Example

    obj.once('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    obj.fire('test', 1, 2); // not going to get handled

start

  • start(
        camera: CameraComponent,
        type: string,
        spaceType: string,
        options?: {
            anchors?: boolean;
            callback?: XrErrorCallback;
            depthSensing?: { dataFormatPreference?: string; usagePreference?: string };
            framebufferScaleFactor?: number;
            imageTracking?: boolean;
            meshDetection?: boolean;
            optionalFeatures?: string[];
            planeDetection?: boolean;
        },
    ): void

  • Attempts to start XR session for provided CameraComponent and optionally fires callback when session is created or failed to create. Integrated XR APIs need to be enabled by providing relevant options.

    Parameters

    • camera: CameraComponent

      It will be used to render XR session and manipulated based on pose tracking.

    • type: string

      Session type. Can be one of the following:

      • XRTYPE_INLINE: Inline - always available type of session. It has limited features availability and is rendered into HTML element.
      • XRTYPE_VR: Immersive VR - session that provides exclusive access to VR device with best available tracking features.
      • XRTYPE_AR: Immersive AR - session that provides exclusive access to VR/AR device that is intended to be blended with real-world environment.
    • spaceType: string

      Reference space type. Can be one of the following:

      • XRSPACE_VIEWER: Viewer - always supported space with some basic tracking capabilities.
      • XRSPACE_LOCAL: Local - represents a tracking space with a native origin near the viewer at the time of creation. It is meant for seated or basic local XR sessions.
      • XRSPACE_LOCALFLOOR: Local Floor - represents a tracking space with a native origin at the floor in a safe position for the user to stand. The y axis equals 0 at floor level. Floor level value might be estimated by the underlying platform. It is meant for seated or basic local XR sessions.
      • XRSPACE_BOUNDEDFLOOR: Bounded Floor - represents a tracking space with its native origin at the floor, where the user is expected to move within a pre-established boundary.
      • XRSPACE_UNBOUNDED: Unbounded - represents a tracking space where the user is expected to move freely around their environment, potentially long distances from their starting point.
    • Optionaloptions: {
          anchors?: boolean;
          callback?: XrErrorCallback;
          depthSensing?: { dataFormatPreference?: string; usagePreference?: string };
          framebufferScaleFactor?: number;
          imageTracking?: boolean;
          meshDetection?: boolean;
          optionalFeatures?: string[];
          planeDetection?: boolean;
      }

      Object with additional options for XR session initialization.

      • Optionalanchors?: boolean

        Set to true to attempt to enable XrAnchors.

      • Optionalcallback?: XrErrorCallback

        Optional callback function called once session is started. The callback has one argument Error - it is null if successfully started XR session.

      • OptionaldepthSensing?: { dataFormatPreference?: string; usagePreference?: string }

        Optional object with depth sensing parameters to attempt to enable XrDepthSensing.

        • OptionaldataFormatPreference?: string

          Optional data format preference for depth sensing, can be 'luminance-alpha' or 'float32' (XRDEPTHSENSINGFORMAT_*), defaults to 'luminance-alpha'. Most preferred and supported will be chosen by the underlying depth sensing system.

        • OptionalusagePreference?: string

          Optional usage preference for depth sensing, can be 'cpu-optimized' or 'gpu-optimized' (XRDEPTHSENSINGUSAGE_*), defaults to 'cpu-optimized'. Most preferred and supported will be chosen by the underlying depth sensing system.

      • OptionalframebufferScaleFactor?: number

        Framebuffer scale factor should be higher than 0.0, by default 1.0 (no scaling). A value of 0.5 will reduce the resolution of an XR session in half, and a value of 2.0 will double the resolution.

      • OptionalimageTracking?: boolean

        Set to true to attempt to enable XrImageTracking.

      • OptionalmeshDetection?: boolean

        Set to true to attempt to enable XrMeshDetection.

      • OptionaloptionalFeatures?: string[]

        Optional features for XRSession start. It is used for getting access to additional WebXR spec extensions.

      • OptionalplaneDetection?: boolean

        Set to true to attempt to enable XrPlaneDetection.

    Returns void

    Example

    button.on('click', function () {
        app.xr.start(camera, pc.XRTYPE_VR, pc.XRSPACE_LOCALFLOOR);
    });

    Example

    button.on('click', function () {
        app.xr.start(camera, pc.XRTYPE_AR, pc.XRSPACE_LOCALFLOOR, {
            anchors: true,
            imageTracking: true,
            depthSensing: { }
        });
    });

updateTargetFrameRate

  • updateTargetFrameRate(frameRate: number, callback?: Function): void

  • Update target frame rate of an XR session to one of supported value provided by supportedFrameRates list.

    Parameters

    • frameRate: number

      Target frame rate. It should be any value from the list of supportedFrameRates.

    • Optionalcallback: Function

      Callback that will be called when frameRate has been updated or failed to update with error provided.

    Returns void

Events

StaticEVENT_AVAILABLE

EVENT_AVAILABLE: string = 'available'

Fired when availability of the XR type is changed. This event is available in two forms. They are as follows:

  1. available - Fired when availability of any XR type is changed. The handler is passed the session type that has changed availability and a boolean representing the availability.
  2. available:[type] - Fired when availability of specific XR type is changed. The handler is passed a boolean representing the availability.

Example

app.xr.on('available', (type, available) => {
    console.log(`XR type ${type} is now ${available ? 'available' : 'unavailable'}`);
});

Example

app.xr.on(`available:${pc.XRTYPE_VR}`, (available) => {
    console.log(`XR type VR is now ${available ? 'available' : 'unavailable'}`);
});

StaticEVENT_END

EVENT_END: string = 'end'

Fired when XR session is ended.

Example

app.xr.on('end', () => {
    // XR session has ended
});

StaticEVENT_ERROR

EVENT_ERROR: string = 'error'

Fired when XR session is failed to start or failed to check for session type support. The handler is passed the Error object related to failure of session start or check of session type support.

Example

app.xr.on('error', (error) => {
    console.error(error.message);
});

StaticEVENT_START

EVENT_START: string = 'start'

Fired when XR session is started.

Example

app.xr.on('start', () => {
    // XR session has started
});

StaticEVENT_UPDATE

EVENT_UPDATE: string = 'update'

Fired when XR session is updated, providing relevant XRFrame object. The handler is passed XRFrame object that can be used for interfacing directly with WebXR APIs.

Example

app.xr.on('update', (frame) => {
    console.log('XR frame updated');
});

Settings

Member Visibility

On This Page

Properties
Accessors
Methods
Events