XRSession.requestAnimationFrame()

Draft
This page is not complete.

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

The requestAnimationFrame() method of the XRSession interface Tells the browser to paint one frame of an animation at which time the browser will call the supplied callback function. The callback will be run once before the next repaint.

This function is conceptually similar to Window.requestAnimationFrame, except its callback takes an XRFrame as an argument in addition to the DOMHighResTimeStamp argument. Similarly, you can cancel a previously scheduled animation via XRSession.cancelAnimationFrame. However, you should not assume any relation between when these two functions (depending on the device) Window.requestAnimationFrame while immersive XR session is active.

Note: Your callback routine must itself call requestAnimationFrame if you want to animate another frame at the next repaint.

Syntax

XRSession.requestAnimationFrame(onXRAnimationFrame);

Parameters

  • time: A DOMHighResTimeStamp object that is provided for compatibility with window.requestAnimationFrame() and will always be 0.
  • xrFrame: An XRFrame providing the data needed to render a single frame of an AR/VR scene. 
XRFrameRequestCallback
The callback function to call when it's time to update your animation for the next repaint. Calls to this function will pass the following arguments

Return value

A long integer, the request id, that uniquely identifies the entry in the callback list. This is a non-zero value, but you may not make any other assumptions about its value. You can pass this value to XRSession.cancelAnimationFrame to cancel the refresh callback request.

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.
    }
  })
})

Warning: Do not rely on XRSession.requestAnimationFrame to call Window.requestAnimationFrame because they are not related.

The following example was taken directly from the spec draft. This example demonstrates a design pattern that ensures seamless transition between non-immersive animations created via Window.requestAnimationFrame and immersive XR animations.

let xrSession = null

function onWindowAnimationFrame(time) {
  window.requestAnimationFrame(onWindowAnimationFrame)

  // This may be called while an immersive session is running on some devices,
  // such as a desktop with a tethered headset. To prevent two loops from
  // rendering in parallel, skip drawing in this one until the session ends.
  if (!xrSession) {
    renderFrame(time, null)
  }
}

// The window animation loop can be started immediately upon the page loading.
window.requestAnimationFrame(onWindowAnimationFrame)

function onXRAnimationFrame(time, xrFrame) {
  xrSession.requestAnimationFrame(onXRAnimationFrame)
  renderFrame(time, xrFrame)
}

function renderFrame(time, xrFrame) {
  // Shared rendering logic.
}

// Assumed to be called by a user gesture event elsewhere in code.
function startXRSession() {
  navigator.xr.requestSession('immersive-vr').then((session) => {
    xrSession = session
    xrSession.addEventListener('end', onXRSessionEnded)
    // Do necessary session setup here.
    // Begin the session’s animation loop.
    xrSession.requestAnimationFrame(onXRAnimationFrame)
  })
}

function onXRSessionEnded() {
  xrSession = null
}

Specifications

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

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
requestAnimationFrame()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

No support  
No support

See also

Document Tags and Contributors

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