XRSession: Methode requestHitTestSource()

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, bevor Sie diese produktiv verwenden.

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

Die requestHitTestSource()-Methode des XRSession-Interfaces gibt ein Promise zurück, das mit einem XRHitTestSource-Objekt aufgelöst wird, welches an XRFrame.getHitTestResults() übergeben werden kann.

Syntax

js
requestHitTestSource(options)

Parameter

options

Ein Objekt mit Konfigurationsoptionen, insbesondere:

space

Der XRSpace, der durch die Hit-Test-Quelle verfolgt wird.

entityTypes Optional

Ein Array, das die Typen von Entitäten angibt, die für die Erstellung der Hit-Test-Quelle verwendet werden. Wenn kein Entitätstyp angegeben wird, enthält das Array standardmäßig ein einziges Element mit dem Typ plane. Mögliche Typen:

  • point: Berechnet die Hit-Test-Ergebnisse basierend auf erkannten charakteristischen Punkten.
  • plane: Berechnet die Hit-Test-Ergebnisse basierend auf erkannten realen Ebenen.
  • mesh: Berechnet die Hit-Test-Ergebnisse basierend auf erkannten Meshes.
offsetRay Optional

Das XRRay-Objekt, das für den Hit-Test verwendet wird. Wenn kein XRRay-Objekt bereitgestellt wurde, wird ein neues XRRay-Objekt ohne Parameter erstellt.

Rückgabewert

Ein Promise, das mit einem XRHitTestSource-Objekt aufgelöst wird.

Ausnahmen

Anstatt echte Ausnahmen zu werfen, lehnt requestHitTestSource() das zurückgegebene Promise mit einem DOMException ab, insbesondere einer der folgenden:

NotSupportedError DOMException

Wird ausgelöst, wenn hit-test keine aktivierte Funktion in XRSystem.requestSession() ist.

InvalidStateError DOMException

Wird ausgelöst, wenn die Sitzung bereits beendet wurde.

NotAllowedError DOMException

Wird ausgelöst, wenn eine unangemessene Anzahl von Anfragen vorliegt. Einige Benutzeragenten können die Nutzung aus Datenschutzgründen einschränken.

Beispiele

Anfordern einer Hit-Test-Quelle

Um eine Hit-Test-Quelle anzufordern, starten Sie eine XRSession mit der aktivierten hit-test-Sitzungsfunktion. Konfigurieren Sie anschließend die Hit-Test-Quelle und speichern Sie sie für die spätere Verwendung in der Frame-Schleife und rufen Sie XRFrame.getHitTestResults() auf, um das Ergebnis zu erhalten.

js
const xrSession = navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["local", "hit-test"],
});

let hitTestSource = null;

xrSession
  .requestHitTestSource({
    space: viewerSpace, // obtained from xrSession.requestReferenceSpace("viewer");
    offsetRay: new XRRay({ y: 0.5 }),
  })
  .then((viewerHitTestSource) => {
    hitTestSource = viewerHitTestSource;
  });

// frame loop
function onXRFrame(time, xrFrame) {
  let hitTestResults = xrFrame.getHitTestResults(hitTestSource);

  // do things with the hit test results
}

Spezifikationen

Specification
WebXR Hit Test Module
# dom-xrsession-requesthittestsource

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch