XRSession.cancelAnimationFrame() — Methode · JavaScript-Referenz

Signatur

XRSession.prototype.cancelAnimationFrame(handle)

Beschreibung

cancelAnimationFrame() gehört zum Interface XRSession der WebXR Device API. Die Methode entfernt einen Callback aus der Frame-Warteschlange der Sitzung, den Sie vorher mit XRSession.requestAnimationFrame() angemeldet haben. Zur Kennzeichnung dient die Ganzzahl (Handle), die requestAnimationFrame() zurückgegeben hat.

Die Methode entspricht window.cancelAnimationFrame(), bezieht sich aber auf die XR-Render-Schleife. Die XR-Sitzung ruft ihre Frame-Callbacks im Takt des XR-Geräts auf (oft 72–120 Hz), nicht im Takt des Bildschirms. Handles aus window.requestAnimationFrame() und aus XRSession.requestAnimationFrame() sind deshalb getrennte Namensräume und lassen sich nicht gegenseitig abbrechen.

Typische Anwendungsfälle:

Die Render-Schleife anhalten, etwa wenn die Anwendung pausiert wird oder die Sichtbarkeit wechselt (visibilitychange der Sitzung).
Vor dem Beenden oder Neuaufsetzen einer Szene aufräumen, damit kein veralteter Callback mehr ausgeführt wird.
Einen einmalig angemeldeten Callback zurücknehmen, bevor er ausgeführt wird.

Weil jeder XR-Frame-Callback sich selbst für den nächsten Frame neu anmelden muss, sollten Sie immer das zuletzt zurückgegebene Handle speichern. Nur dieses Handle beendet die Schleife zuverlässig.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	number		Die ganzzahlige Kennung, die ein vorheriger Aufruf von `XRSession.requestAnimationFrame()` auf derselben Sitzung zurückgegeben hat. Ist der Wert unbekannt oder wurde der Callback schon ausgeführt, passiert nichts.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Render-Schleife starten und wieder anhalten

let session = null;
let frameHandle = 0;

const onXRFrame = (time, frame) => {
  // Für den nächsten Frame neu anmelden und das Handle merken
  frameHandle = frame.session.requestAnimationFrame(onXRFrame);
  // ... Szene zeichnen ...
};

const startXR = async () => {
  session = await navigator.xr.requestSession('immersive-vr');
  const gl = document.createElement('canvas').getContext('webgl2', { xrCompatible: true });
  await session.updateRenderState({ baseLayer: new XRWebGLLayer(session, gl) });
  frameHandle = session.requestAnimationFrame(onXRFrame);
};

const pauseXR = () => {
  session?.cancelAnimationFrame(frameHandle);
  console.log('XR-Render-Schleife angehalten');
};

document.querySelector('#enter-vr').addEventListener('click', startXR);
document.querySelector('#pause').addEventListener('click', pauseXR);

XR-Render-Schleife angehalten

Schleife anhalten, solange die Sitzung verborgen ist

const setupVisibilityHandling = (session, onXRFrame) => {
  let handle = session.requestAnimationFrame(onXRFrame);

  session.addEventListener('visibilitychange', () => {
    if (session.visibilityState === 'hidden') {
      session.cancelAnimationFrame(handle);
      console.log('Pausiert:', session.visibilityState);
    } else {
      handle = session.requestAnimationFrame(onXRFrame);
      console.log('Fortgesetzt:', session.visibilityState);
    }
  });

  // Die Schleife meldet sich selbst neu an und aktualisiert das Handle
  return (next) => { handle = next; };
};

Pausiert: hidden Fortgesetzt: visible

Einmaligen Callback vor der Ausführung zurücknehmen

const scheduleScreenshot = (session) => {
  const handle = session.requestAnimationFrame((time, frame) => {
    console.log('Screenshot-Frame bei', time.toFixed(1), 'ms');
  });

  // Der Nutzer bricht sofort ab – der Callback wird nie ausgeführt
  session.cancelAnimationFrame(handle);
  console.log('Screenshot abgebrochen, Handle:', handle);
};

navigator.xr?.requestSession('inline').then(scheduleScreenshot);

Screenshot abgebrochen, Handle: 1

// Wichtig · Fallstricke

Handle stets aktualisieren: Eine XR-Schleife meldet sich in jedem Frame neu an. Wenn Sie ein altes Handle abbrechen, wirkt das nicht, und die Schleife läuft weiter.
Nicht mit window.cancelAnimationFrame() verwechseln: Handles der Fenster- und der XR-Schleife sind unabhängig voneinander. Ein XR-Handle an window.cancelAnimationFrame() zu übergeben, hat keine Wirkung, und umgekehrt genauso.
Die Handles sind an die Sitzung gebunden. Handles einer anderen oder bereits beendeten XRSession bewirken nichts. Endet die Sitzung (end-Ereignis), werden ausstehende Callbacks ohnehin nicht mehr aufgerufen.
Ungültige oder bereits ausgeführte Handles lösen keinen Fehler aus. Der Aufruf wird still ignoriert.
Kompatibilität: WebXR steht nur in einem sicheren Kontext (HTTPS) zur Verfügung und unterstützt vor allem Chromium-basierte Browser sowie VR-Headset-Browser. Firefox und Desktop-Safari unterstützen es nicht, visionOS-Safari nur eingeschränkt. Prüfen Sie vorab mit 'xr' in navigator und navigator.xr.isSessionSupported(). Eine Permissions-Policy (xr-spatial-tracking) kann den Zugriff in iframes sperren.

Siehe auch

XRSession.requestAnimationFrame() XRSession XRFrame XRSession.end() window.cancelAnimationFrame()