API Reference

Class List

pc.XrManager

Extends: pc.EventHandler

Manage and update XR session and its states.

Summary

Properties

active

True if XR session is running.

camera

Active camera for which XR session is running or null.

hitTest

provides ability to hit test representation of real world geometry of underlying AR system.

input

provides access to Input Sources.

session

provides access to spaceType

Returns reference space type of currently running XR session or null if no session is running.

supported

True if XR is supported.

type

Returns type of currently running XR session or null if no session is running.

Methods

end

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

isAvailable

Check if specific type of session is available

start

Attempts to start XR session for provided pc.CameraComponent and optionally fires callback when session is created or failed to create.

Events

available:[type]

Fired when availability of specific XR type is changed.

available

Fired when availability of specific XR type is changed.

end

Fired when XR session is ended

error

Fired when XR session is failed to start or failed to check for session type support.

start

Fired when XR session is started

update

Fired when XR session is updated, providing relevant XRFrame object.

Inherited

Methods

fire

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

hasEvent

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

off

Detach an event handler from an event.

on

Attach an event handler to an event.

once

Attach an event handler to an event.

Details

Constructor

XrManager(app)

Manage and update XR session and its states.

Parameters

apppc.Application

The main application.

Properties

booleanactive

True if XR session is running.

pc.Entity, nullcamera

Active camera for which XR session is running or null.

pc.XrHitTesthitTest

provides ability to hit test representation of real world geometry of underlying AR system.

pc.XrInputinput

provides access to Input Sources.

object, nullsession

provides access to XRSession of WebXR

string, nullspaceType

Returns reference space type of currently running XR session or null if no session is running. Can be any of pc.XRSPACE_*.

booleansupported

True if XR is supported.

string, nulltype

Returns type of currently running XR session or null if no session is running. Can be any of pc.XRTYPE_*.

Methods

end([callback])

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

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

Parameters

callbackpc.callbacks.XrError

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

isAvailable(type)

Check if specific type of session is available

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

Parameters

typestring

session type. Can be one of the following:

  • pc.XRTYPE_INLINE: Inline - always available type of session. It has limited features availability and is rendered into HTML element.
  • pc.XRTYPE_VR: Immersive VR - session that provides exclusive access to VR device with best available tracking features.
  • pc.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.

start(camera, type, spaceType, [options])

Attempts to start XR session for provided pc.CameraComponent and optionally fires callback when session is created or failed to create.

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

Parameters

camerapc.CameraComponent

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

typestring

session type. Can be one of the following:

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

reference space type. Can be one of the following:

  • pc.XRSPACE_VIEWER: Viewer - always supported space with some basic tracking capabilities.
  • pc.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.
  • pc.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.
  • pc.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.
  • pc.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.
optionsobject

object with additional options for XR session initialization.

options.optionalFeaturesstring[]

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

options.callbackpc.callbacks.XrError

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

Events

available:[type]

Fired when availability of specific XR type is changed.

app.xr.on('available:' + pc.XRTYPE_VR, function (available) {
    console.log('Immersive VR session is now ' + (available ? 'available' : 'unavailable'));
});

Parameters

availableboolean

True if specified session type is now available.

available

Fired when availability of specific XR type is changed.

app.xr.on('available', function (type, available) {
    console.log('"' + type + '" XR session is now ' + (available ? 'available' : 'unavailable'));
});

Parameters

typestring

The session type that has changed availability.

availableboolean

True if specified session type is now available.

end

Fired when XR session is ended

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

error

Fired when XR session is failed to start or failed to check for session type support.

app.xr.on('error', function (ex) {
    // XR session has failed to start, or failed to check for session type support
});

Parameters

errorError

Error object related to failure of session start or check of session type support.

start

Fired when XR session is started

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

update

Fired when XR session is updated, providing relevant XRFrame object.

app.xr.on('update', function (frame) {

});

Parameters

frameobject

XRFrame object that can be used for interfacing directly with WebXR APIs.

Inherited

Methods

fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])

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

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

Parameters

nameobject

Name of event to fire.

arg1*

First argument that is passed to the event handler.

arg2*

Second argument that is passed to the event handler.

arg3*

Third argument that is passed to the event handler.

arg4*

Fourth argument that is passed to the event handler.

arg5*

Fifth argument that is passed to the event handler.

arg6*

Sixth argument that is passed to the event handler.

arg7*

Seventh argument that is passed to the event handler.

arg8*

Eighth argument that is passed to the event handler.

Returns

pc.EventHandler

Self for chaining.

hasEvent(name)

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

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

Parameters

namestring

The name of the event to test.

Returns

boolean

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

off([name], [callback], [scope])

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.

var 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 hander functions, called 'test' with scope this

Parameters

namestring

Name of the event to unbind.

callbackpc.callbacks.HandleEvent

Function to be unbound.

scopeobject

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

Returns

pc.EventHandler

Self for chaining.

on(name, callback, [scope])

Attach an event handler to an event.

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

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

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

scopeobject

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

Returns

pc.EventHandler

Self for chaining.

once(name, callback, [scope])

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

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

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

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

scopeobject

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

Returns

pc.EventHandler

Self for chaining.