XRSession: requestAnimationFrame()-Methode

Limited availability

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

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die Methode requestAnimationFrame() von XRSession plant, ähnlich wie die gleichnamige Methode von Window, einen Rückruf, der beim nächsten Mal ausgeführt wird, wenn der Browser bereit ist, die virtuelle Umgebung der Sitzung auf das XR-Display zu zeichnen. Der angegebene Rückruf wird einmal vor der nächsten Neuzeichnung ausgeführt; wenn Sie möchten, dass er für die folgende Neuzeichnung ausgeführt wird, müssen Sie requestAnimationFrame() erneut aufrufen. Dies kann innerhalb des Rückrufs selbst geschehen.

Der Rückruf nimmt zwei Parameter als Eingaben: ein XRFrame, das den Zustand aller verfolgten Objekte für die Sitzung beschreibt, und einen Zeitstempel, den Sie verwenden können, um alle erforderlichen Animationsaktualisierungen zu berechnen.

Sie können eine zuvor geplante Animation stornieren, indem Sie cancelAnimationFrame() aufrufen.

Hinweis: Trotz der offensichtlichen Ähnlichkeiten zwischen diesen Methoden und der globalen requestAnimationFrame()-Funktion, die von der Window-Schnittstelle bereitgestellt wird, sollten Sie diese nicht als austauschbar behandeln. Es gibt keine Garantie, dass die letztere Methode überhaupt funktioniert, während eine immersive XR-Sitzung im Gange ist.

Syntax

requestAnimationFrame(animationFrameCallback)

Parameter

animationFrameCallback

Eine Funktion, die vor der nächsten Neuzeichnung aufgerufen wird, damit Sie die XR-Szene basierend auf der verstrichenen Zeit, Animationen, Benutzereingabenänderungen usw. aktualisieren und rendern können. Der Rückruf erhält zwei Parameter als Eingabe:

time: Ein DOMHighResTimeStamp, der den zeitlichen Versatz angibt, zu dem der aktualisierte Zuschauerstatus vom WebXR-Gerät empfangen wurde.
xrFrame: Ein XRFrame-Objekt, das den Zustand der Objekte beschreibt, die von der Sitzung verfolgt werden. Dies kann verwendet werden, um die Positionen des Betrachters und der Szene selbst sowie andere Informationen zu erhalten, die für das Rendern eines Bildes einer AR- oder VR-Szene benötigt werden.

Rückgabewert

Ein ganzzahliger Wert, der als eindeutige, von Null verschiedene ID oder Handler dient, den Sie an cancelAnimationFrame() übergeben können, wenn Sie die ausstehende Anforderungs-Rahmen-Animation löschen müssen.

Beispiele

Das folgende Beispiel fordert XRSession im "inline"-Modus an, damit es in einem HTML-Element angezeigt werden kann (ohne dass ein separates AR- oder VR-Gerät benötigt wird).

Hinweis: Eine echte Anwendung sollte überprüfen, ob das Gerät und der User Agent die WebXR-API überhaupt unterstützen und dann, dass beide den gewünschten Sitzungsmodus über XRSystem.isSessionSupported() unterstützen.

// Obtain XR object
const XR = navigator.xr;

// Request a new XRSession
XR.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.
    }
  });
});

Das folgende Beispiel stammt direkt aus dem Entwurfsstandard. Dieses Beispiel zeigt ein Designmuster, das einen nahtlosen Übergang zwischen nicht-immersiven Animationen, die über Window.requestAnimationFrame erstellt wurden, und immersiven XR-Animationen gewährleistet.

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;
}

Spezifikationen

Specification
WebXR Device API # dom-xrsession-requestanimationframe