XRSession

Draft
This page is not complete.

Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The XRSession of the WebXR Device API provides the means to interact with an AR/VR device, providing features such as polling the viewer space (viewer pose), getting information about the user's environment, and presenting imagery to the user. To get an XRSession call XR.requestSession().

Attributes

XRSession.environmentBlendMode Read only
Returns this session's blend mode which denotes how much of the real-world environment is visible through the XR device and how the device will blend the device imagery with it.
XRSession.visibilityState Read only  
Returns this session's visibility state which indicates whether the images of the session are visible to the user.
XRSession.renderState Read only  
Returns this session's XRRenderState which represents configurable options which affect how the imagery is rendered.
XRSession.inputSources Read only  
Returns a list of this session's XRInputSources.

Methods

XRSession.updateRenderState()
Submit new XRRenderState which determines configurable rendering options.
XRSession.requestReferenceSpace()
Returns a Promise that resolves with either an instance of XRReferenceSpace or of XRBoundedReferenceSpace which contains information about the current session tracking behavior.
XRSession.requestAnimationFrame()
Schedule a callback to run before the next animation frame.
XRSession.cancelAnimationFrame()
Remove previously scheduled callback passed into XRSession.requestAnimationFrame().
XRSession.end()
End the current XRSession.

Event handlers

XRSession.onend
The event handler for the end event, which is dispatched after the XR session ends and all related hardware-specific routines are completed.
XRSession.onselect
The event handler for the select event, which is dispatched when a user presses a trigger, touchpad, or button, speaks a command, or makes a hand gesture.
XRSession.oninputsourceschange
The event handler for the inputsourcechange event, which is dispatched when session's list of active XR input sources has changed.
XRSession.onselectstart
The event handler for the selectstart event, which is dispatched when user starts making some sort of selection by pressing a trigger, touchpad, or button, speaking a command, or making a hand gesture.
XRSession.onselectend
The event handler for the selectend event, which is dispatched when user finishes making some sort of selection by releasing a trigger, touchpad, or button, finishes speaking a command, or makes a hand gesture.
XRSession.onvisibilitychange
The event handler for the visibilitychange event, which is dispatched when the visibility state of the XR session changes.

Example

The following example requests XRSession with "inline" mode so that it can be displayed in an HTML element (without the need for a separate AR or VR device).

Note: A real application should check that the device and the User Agent support WebXR API at all and then that they both support the desired session type via XR.supportsSession.

// Obtain XR object
const XR = navigator.xr

// Request a new XRSession
XR.requestSession("inline").then((xrSession) => {
  xrSession.requestAnimationFrame((time, xrFrame) => {
    let viewer = xrFrame.getViewerPose(xrReferenceSpace)

    gl.bindFramebuffer(xrWebGLLayer.framebuffer)
    for (xrView of viewer.views) {
      let xrViewport = xrWebGLLayer.getViewport(xrView)
      gl.viewport(xrViewport.x, xrViewport.y, xrViewport.width, xrViewport.height)

    // WebGL draw calls will now be rendered into the appropriate viewport.
    }
  })
})

Specifications

Specification Status Comment
WebXR Device API
The definition of 'XRSession' in that specification.
Working Draft Initial definition.

Browser compatibility

No compatibility data found. Please contribute data for "api.XRSession" (depth: 1) to the MDN compatibility data repository.

Document Tags and Contributors

Contributors to this page: jpmedley, bershanskiy
Last updated by: jpmedley,