Manage and update XR session and its states.

Hierarchy (view full)

Constructors

Properties

_available: {} = {}

Type declaration

    _baseLayer: XRWebGLLayer = null
    _camera: CameraComponent = null
    _depthFar: number = 1000
    _depthNear: number = 0.1
    _height: number = 0
    _localPosition: Vec3 = ...
    _localRotation: Quat = ...
    _session: XRSession = null
    _spaceType: string = null
    _supported: boolean = ...
    _type: string = null
    _width: number = 0
    anchors: XrAnchors

    Provides access to Anchors.

    hitTest: XrHitTest

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

    input: XrInput

    Provides access to Input Sources.

    Accessors

    Methods

    • Private

      Parameters

      • type: string

        Session type.

      • spaceType: string

        Reference space type.

      • options: any

        Session options.

      • callback: XrErrorCallback

        Error callback.

      Returns void

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

      Parameters

      • Optional callback: 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 an event, all additional arguments are passed on to the event listener.

      Parameters

      • name: string

        Name of event to fire.

      • Optional arg1: any

        First argument that is passed to the event handler.

      • Optional arg2: any

        Second argument that is passed to the event handler.

      • Optional arg3: any

        Third argument that is passed to the event handler.

      • Optional arg4: any

        Fourth argument that is passed to the event handler.

      • Optional arg5: any

        Fifth argument that is passed to the event handler.

      • Optional arg6: any

        Sixth argument that is passed to the event handler.

      • Optional arg7: any

        Seventh argument that is passed to the event handler.

      • Optional arg8: any

        Eighth argument that is passed to the event handler.

      Returns EventHandler

      Self for chaining.

      Example

      obj.fire('test', 'This is the message');
      
    • 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
    • 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

      • callback: XrRoomCaptureCallback

        Callback that will be fired once capture is complete or failed.

      Returns void

      Example

      this.app.xr.initiateRoomCapture((err) => {
      if (err) {
      // capture failed
      return;
      }
      // capture was successful
      });
    • 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
      }
    • 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

      • Optional name: string

        Name of the event to unbind.

      • Optional callback: HandleEventCallback

        Function to be unbound.

      • Optional scope: 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
    • 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.

      • Optional scope: 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();
    • 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.

      • Optional scope: 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
    • 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.
      • Optional options: {
            anchors: boolean;
            callback: XrErrorCallback;
            depthSensing: {
                dataFormatPreference: string;
                usagePreference: string;
            };
            imageTracking: boolean;
            meshDetection: boolean;
            optionalFeatures: string[];
            planeDetection: boolean;
        }

        Object with additional options for XR session initialization.

        • anchors: boolean

          Set to true to attempt to enable XrAnchors.

        • callback: XrErrorCallback

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

        • depthSensing: {
              dataFormatPreference: string;
              usagePreference: string;
          }

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

          • dataFormatPreference: string
          • usagePreference: string
        • imageTracking: boolean

          Set to true to attempt to enable XrImageTracking.

        • meshDetection: boolean

          Set to true to attempt to enable XrMeshDetection.

        • optionalFeatures: string[]

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

        • planeDetection: 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: { }
      });
      });

    Events

    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'}`);
    });
    EVENT_END: string = 'end'

    Fired when XR session is ended.

    Example

    app.xr.on('end', () => {
    // XR session has ended
    });
    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);
    });
    EVENT_START: string = 'start'

    Fired when XR session is started.

    Example

    app.xr.on('start', () => {
    // XR session has started
    });
    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');
    });

    Generated using TypeDoc v0.25.9