XRSystem: requestSession() Methode

mode

Ein String, der den XR-Sitzungsmodus definiert. Die unterstützten Modi sind:

• Experimentell immersive-ar: Die Ausgabe der Sitzung erhält exklusiven Zugriff auf das immersive Gerät, jedoch wird der gerenderte Inhalt mit der realen Umgebung vermischt. Der environmentBlendMode der Sitzung gibt die verwendete Methode zum Mischen des Inhalts an.
• immersive-vr: Gibt an, dass die gerenderte Sitzung mit einem immersiven XR-Gerät im VR-Modus angezeigt wird; sie soll nicht überlagert oder in die Umgebung integriert werden. Der environmentBlendMode soll wenn möglich opaque sein, kann aber additive sein, wenn es die Hardware erfordert.
• inline: Die Ausgabe wird inline im Kontext eines Elements in einem standardmäßigen HTML-Dokument präsentiert, anstatt den gesamten visuellen Raum zu nutzen. Inline-Sitzungen können entweder im Mono- oder Stereo-Modus präsentiert werden und können je nach Benutzeragent sowohl mit als auch ohne Betrachterverfolgung verfügbar sein. Inline-Sitzungen erfordern keine spezielle Hardware und sollten auf jedem User-Agent, der die WebXR-API unterstützt, verfügbar sein.

options Optional

Ein Objekt zur Konfiguration der XRSession. Wenn keine Optionen enthalten sind, verwendet das Gerät eine Standard-Feature-Konfiguration für alle Optionen.

• requiredFeatures Optional: Ein Array von Werten, die die zurückgegebene XRSession unterstützen muss. Siehe Session-Features unten.
• optionalFeatures Optional: Ein Array von Werten, die Features identifizieren, die die zurückgegebene XRSession optional unterstützen kann. Siehe Session-Features unten.
• domOverlay Optional: Ein Objekt mit einer erforderlichen root-Eigenschaft, die das Overlay-Element spezifiziert, das dem Benutzer als Inhalt des DOM-Overlays angezeigt wird. Siehe das Beispiel unten.
• depthSensing Optional: Ein Objekt mit zwei erforderlichen Eigenschaften usagePreference und dataFormatPreference, um die Durchführung der Tiefenerfassung zu konfigurieren. Siehe das Beispiel unten.

Ein Promise, das ein XRSession-Objekt auflöst, wenn das Gerät und der Benutzeragent den angeforderten Modus und die Features unterstützen.

Diese Methode wirft keine echten Ausnahmen; stattdessen lehnt sie das zurückgegebene Promise ab und übergibt eine DOMException, deren name einer der folgenden ist:

InvalidStateError DOMException

Wird zurückgegeben, wenn der angeforderte Sitzungsmodus immersive-vr ist, aber bereits eine immersive VR-Sitzung entweder aktiv oder im Aufbau ist. Es kann jeweils nur eine immersive VR-Sitzung vorhanden sein.

NotSupportedError DOMException

Wird zurückgegeben, wenn kein WebXR-kompatibles Gerät verfügbar ist oder das Gerät den angegebenen sessionMode nicht unterstützt; dies kann auch ausgelöst werden, wenn einer der erforderlichen Optionen nicht unterstützt wird.

SecurityError DOMException

Wird zurückgegeben, wenn die Erlaubnis zum Betreten des bestimmten XR-Modus verweigert wird. Dies kann aus mehreren Gründen geschehen, die in Berechtigungen und Sicherheit ausführlicher behandelt werden.

Die folgenden Sitzungs-Features und Referenzräume können entweder als optionalFeatures oder requiredFeatures angefordert werden.

anchors

Aktiviert die Verwendung von XRAnchor-Objekten.

bounded-floor

Ähnlich wie der local-Typ, außer dass der Benutzer sich nicht außerhalb einer vorher festgelegten Grenze, die durch die boundsGeometry im zurückgegebenen Objekt angegeben wird, bewegen soll.

depth-sensing

Aktiviert die Möglichkeit, Tiefeninformationen mithilfe von XRDepthInformation-Objekten zu erhalten.

dom-overlay

Aktiviert die Möglichkeit, ein DOM-Overlay-Element zu spezifizieren, das dem Benutzer angezeigt wird.

hand-tracking

Ermöglicht die Erfassung der Artikulationshaltung der Hand von handbasierten Eingabereglern (siehe XRHand und XRInputSource.hand).

hit-test

Aktiviert Funktionen für den Hit-Test gegen reale Geometrien.

layers

Ermöglicht die Erstellung verschiedener Schichttypen (außer XRProjectionLayer).

light-estimation

Ermöglicht die Schätzung von Lichtverhältnissen in der Umgebung mithilfe von XRLightEstimate-Objekten.

local

Ermöglicht einen Verfolgungsraum, dessen nativer Ursprung sich in der Nähe der Position des Betrachters zum Zeitpunkt der Sitzungsführung befindet. Die genaue Position hängt von der zugrunde liegenden Plattform und Implementierung ab. Der Benutzer soll sich nicht viel weiter als seine Ausgangsposition bewegen, und die Verfolgung ist für diesen Anwendungsfall optimiert.

local-floor

Ähnlich dem local-Typ, außer dass die Ausgangsposition an einem sicheren Standort für den Benutzer platziert wird, wobei der Wert der y-Achse auf 0 am Boden liegt. Wenn diese Bodenhöhe nicht bekannt ist, schätzt der Benutzeragent die Bodenhöhe. Wenn die geschätzte Bodenhöhe ungleich null ist, wird erwartet, dass der Browser sie entsprechend auf die nächste Ganzzahl rundet, um Fingerprinting zu vermeiden (wahrscheinlich auf den nächsten Zentimeter).

secondary-views

Ermöglicht XRView-Objekte als sekundäre Ansichten. Dies kann für Erst-Person-Ansichten, die zur Videofortführung verwendet werden, oder für "Quad-Ansichten", bei denen zwei Ansichten pro Auge sind, mit unterschiedlichen Auflösungen und Sichtfeldern genutzt werden.

unbounded

Ermöglicht einen Verfolgungsraum, der Benutzern totale Bewegungsfreiheit erlaubt, möglicherweise über extreme Entfernungen von ihrem Ursprungsstandort hinweg. Der Betrachter wird nicht verfolgt; die Verfolgung ist auf Stabilität rund um den aktuellen Position des Benutzers optimiert, sodass der native Ursprung driftet, um dies zu ermöglichen.

viewer

Ermöglicht einen Verfolgungsraum, dessen nativer Ursprung die Position und Orientierung des Betrachters verfolgt.

Mehrere Sitzungs-Features und die verschiedenen Referenzräume haben minimale Sicherheits- und Datenschutzanforderungen, wie etwa das Einholen der Benutzererlaubnis und/oder das Einrichten der Permissions-Policy: xr-spatial-tracking-Richtlinie. Siehe auch Berechtigungen und Sicherheit für weitere Details.

Siehe auch transiente Benutzeraktivierung.

Das folgende Beispiel ruft requestSession() auf und fordert eine "immersive-vr"-Sitzung an. Wenn das Promise aufgelöst wird, richtet es eine Sitzung ein und startet die Animationsschleife.

navigator.xr
  .requestSession("immersive-vr")
  .then((xrSession) => {
    xrSession.addEventListener("end", onXRSessionEnded);
    // Do necessary session setup here.
    // Begin the session's animation loop.
    xrSession.requestAnimationFrame(onXRAnimationFrame);
  })
  .catch((error) => {
    // "immersive-vr" sessions are not supported
    console.error(
      "'immersive-vr' isn't supported, or an error occurred activating VR!",
    );
  });

Das folgende Beispiel zeigt, wie isSessionSupported() und requestSession() verwendet werden. Zuerst wird geprüft, ob WebXR verfügbar ist, indem das Vorhandensein von navigator.xr überprüft wird. Dann wird isSessionSupported() aufgerufen, wobei die gewünschte Sitzungsoption übergeben wird, bevor die Steuerelemente für das Betreten von XR aktiviert werden. Das Hinzufügen von Steuerelementen ist notwendig, weil das Betreten von XR einen Benutzeraktion erfordert. Abschließend ruft die Methode onButtonClicked() requestSession() auf, wobei dieselbe Sitzungsoption verwendet wird, die auch an isSessionSupported() übergeben wurde.

if (navigator.xr) {
  navigator.xr.isSessionSupported("immersive-vr").then((isSupported) => {
    if (isSupported) {
      immersiveButton.addEventListener("click", onButtonClicked);
      immersiveButton.textContent = "Enter XR";
      immersiveButton.disabled = false;
    } else {
      console.error("WebXR doesn't support immersive-vr mode!");
    }
  });
} else {
  console.error("WebXR is not available!");
}

function onButtonClicked() {
  if (!xrSession) {
    navigator.xr.requestSession("immersive-vr").then((session) => {
      xrSession = session;
      // onSessionStarted() not shown for reasons of brevity and clarity.
      onSessionStarted(xrSession);
    });
  } else {
    // Button is a toggle button.
    xrSession.end().then(() => (xrSession = null));
  }
}

Erfordern eines uneingeschränkten Erlebnisses, bei dem der Benutzer sich frei in seiner physischen Umgebung bewegen kann:

navigator.xr.requestSession("immersive-vr", {
  requiredFeatures: ["unbounded"],
});

Hier kann der Anrufer sowohl CPU- als auch GPU-optimierte Nutzung sowie die Formate "luminance-alpha" und "float32" handhaben. Die Reihenfolge gibt eine Präferenz für die CPU-Nutzung und "luminance-alpha" an:

navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["depth-sensing"],
  depthSensing: {
    usagePreference: ["cpu-optimized", "gpu-optimized"],
    dataFormatPreference: ["luminance-alpha", "float32"],
  },
});