XRSession: requestAnimationFrame() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental:This is anexperimental technology
Check theBrowser compatibility table carefully before using this in production.

Secure context: This feature is available only insecure contexts (HTTPS), in some or allsupporting browsers.

TheXRSessionmethodrequestAnimationFrame(), much like theWindow method of the same name, schedules a callback to be executed thenext time the browser is ready to paint the session's virtual environment to the XRdisplay. The specified callback is executed once before the next repaint; ifyou wish for it to be executed for the following repaint, you mustcallrequestAnimationFrame() again. This can be done from within thecallback itself.

The callback takes two parameters as inputs: anXRFrame describing thestate of all tracked objects for the session, and a timestamp you can use to computeany animation updates needed.

You can cancel a previously scheduled animation by callingcancelAnimationFrame().

Note:Despite the obvious similarities between these methods and theglobalrequestAnimationFrame() functionprovided by theWindow interface, youmust not treat these asinterchangeable. There isno guarantee that the latter will work at all whilean immersive XR session is underway.

Syntax

requestAnimationFrame(animationFrameCallback)

Parameters

animationFrameCallback

A function which is called before the next repaint in order to allow you to updateand render the XR scene based on elapsed time, animation, user input changes, and soforth. The callback receives as input two parameters:

time: ADOMHighResTimeStamp indicating the time offset at which theupdated viewer state was received from the WebXR device.
xrFrame: AnXRFrame object describing the state of the objects beingtracked by the session. This can be used to obtain the poses of the viewer and thescene itself, as well as other information needed to render a frame of an AR or VRscene.

Return value

An integer value which serves as a unique, non-zero ID or handle you may pass tocancelAnimationFrame() if you need toremove the pending animation frame request.

Examples

The following example requestsXRSession with "inline" mode so that it canbe 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 UserAgent support WebXR API at all and then that they both support the desired sessiontype viaXRSystem.isSessionSupported().

// Obtain XR objectconst XR = navigator.xr;// Request a new XRSessionXR.requestSession("inline").then((xrSession) => {  xrSession.requestAnimationFrame((time, xrFrame) => {    const viewer = xrFrame.getViewerPose(xrReferenceSpace);    gl.bindFramebuffer(xrWebGLLayer.framebuffer);    for (const xrView of viewer.views) {      const 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.    }  });});

The following example was taken directly from the spec draft. This example demonstratesa design pattern that ensures seamless transition between non-immersive animationscreated viaWindow.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;}