XRHitTestSource.cancel() — Methode · JavaScript-Referenz

Signatur

XRHitTestSource.prototype.cancel()

Beschreibung

Ein XRHitTestSource-Objekt entsteht über XRSession.requestHitTestSource() oder XRSession.requestHitTestSourceForTransientInput(). Solange es aktiv ist, berechnet die XR-Laufzeit in jedem Frame, wo ein Strahl (z. B. aus der Blickrichtung des Geräts) auf reale Flächen trifft. Die Ergebnisse holt man mit XRFrame.getHitTestResults() ab.

Mit cancel() meldet man diesen Hit-Test ab. Danach berechnet die Laufzeit für diese Quelle nichts mehr. Das spart Rechenzeit und Akku, was vor allem auf Mobilgeräten wichtig ist. Typische Fälle: Der Nutzer hat ein Objekt platziert und braucht kein Fadenkreuz mehr, man wechselt den Interaktionsmodus, oder die Sitzung wird aufgeräumt.

Die Methode nimmt keine Argumente, gibt undefined zurück und wirkt sofort. Eine abgebrochene Quelle lässt sich nicht wieder aktivieren. Für einen neuen Hit-Test muss man mit requestHitTestSource() eine neue Quelle anfordern.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Hit-Test-Quelle anfordern und nach dem Platzieren abmelden

let hitTestSource = null;

const startAR = async () => {
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['hit-test', 'local']
  });
  const viewerSpace = await session.requestReferenceSpace('viewer');
  const localSpace = await session.requestReferenceSpace('local');
  hitTestSource = await session.requestHitTestSource({ space: viewerSpace });

  // Beim Tippen: Objekt platzieren und Hit-Test beenden
  session.addEventListener('select', () => {
    if (hitTestSource) {
      hitTestSource.cancel();
      hitTestSource = null;
      console.log('Hit-Test beendet – Objekt platziert');
    }
  });

  const onFrame = (time, frame) => {
    session.requestAnimationFrame(onFrame);
    if (!hitTestSource) return;
    const results = frame.getHitTestResults(hitTestSource);
    if (results.length > 0) {
      const pose = results[0].getPose(localSpace);
      // Fadenkreuz an pose.transform ausrichten …
    }
  };
  session.requestAnimationFrame(onFrame);
};

Hit-Test beendet – Objekt platziert

Aufräumen beim Beenden der Sitzung

const setupCleanup = (session, sources) => {
  session.addEventListener('end', () => {
    // Alle noch aktiven Quellen abmelden
    for (const source of sources) {
      source.cancel();
    }
    sources.length = 0;
    console.log('Alle Hit-Test-Quellen freigegeben');
  });
};

// Aufruf: setupCleanup(session, [hitTestSource]);

Alle Hit-Test-Quellen freigegeben

Quelle für flüchtige Eingaben (Touch) ersetzen

let transientSource = null;

const switchToTouchHitTest = async (session) => {
  // Alte Quelle abmelden, bevor eine neue angefordert wird
  transientSource?.cancel();
  transientSource = await session.requestHitTestSourceForTransientInput({
    profile: 'generic-touchscreen'
  });
  console.log('Neue Touch-Hit-Test-Quelle aktiv');
};

Neue Touch-Hit-Test-Quelle aktiv

// Wichtig · Fallstricke

Nicht wiederverwendbar: Nach cancel() ist die Quelle dauerhaft ungültig. Setzt man die Variable danach nicht auf null und ruft trotzdem XRFrame.getHitTestResults() damit auf, wirft der Aufruf einen InvalidStateError. Es gibt keine Methode zum Reaktivieren.
Mehrfacher Aufruf: Wird cancel() auf einer bereits abgebrochenen Quelle aufgerufen, wirft die Methode laut Spezifikation einen InvalidStateError. Deshalb die Referenz nach dem Abbrechen verwerfen oder vorher prüfen.
Ressourcen: Aktive Quellen kosten in jedem Frame Rechenzeit. Nicht mehr benötigte Quellen sollte man immer abmelden, statt ihre Ergebnisse nur zu ignorieren.
Sitzungsende: Endet die XRSession, werden die zugehörigen Quellen automatisch ungültig. Ausdrückliches Aufräumen macht den Code trotzdem klarer.
Kompatibilität: Die Methode gehört zum experimentellen WebXR Hit Test Module. Unterstützt wird sie vor allem von Chromium-Browsern auf Android mit ARCore. Firefox und Safari (Desktop/iOS) unterstützen sie nicht. Voraussetzungen sind ein sicherer Kontext (HTTPS) und das angeforderte Feature 'hit-test'.

Siehe auch

XRHitTestSource XRSession.requestHitTestSource() XRSession.requestHitTestSourceForTransientInput() XRFrame.getHitTestResults() XRTransientInputHitTestSource.cancel() XRHitTestResult MediaKeyStatusMap.values()