XRSystem: Methode requestSession()

mode

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

• Experimentell immersive-ar: Dem Ausgabegerät der Sitzung wird exklusiver Zugriff gewährt, aber die gerenderten Inhalte werden mit der realen Umgebung vermischt. Der environmentBlendMode der Sitzung gibt die Methode an, die zum Mischen der Inhalte verwendet werden soll.
• immersive-vr: Gibt an, dass die gerenderte Sitzung in VR-Modus mit einem immersiven XR-Gerät angezeigt wird; sie soll nicht überlagert oder in die Umgebung integriert werden. Der environmentBlendMode sollte nach Möglichkeit opaque sein, könnte jedoch additive sein, wenn die Hardware dies erfordert.
• inline: Die Ausgabe wird inline im Kontext eines Elements in einem Standard-HTML-Dokument angezeigt, anstatt den gesamten visuellen Raum zu belegen. Inline-Sitzungen können entweder im Mono- oder Stereo-Modus präsentiert werden und können mit oder ohne Benutzerrichtungserkennung verfügbar sein. Inline-Sitzungen erfordern keine spezielle Hardware und sollten in 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 Standardkonfiguration für alle Optionen.

• requiredFeatures Optional: Ein Array von Werten, die die zurückgegebene XRSession unterstützen muss. Siehe Sitzungsfunktionen unten.
• optionalFeatures Optional: Ein Array von Werten, die Funktionen identifizieren, die die zurückgegebene XRSession optional unterstützen kann. Siehe Sitzungsfunktionen unten.
• domOverlay Optional: Ein Objekt mit einer erforderlichen root-Eigenschaft, die das Overlay-Element angibt, 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 Tiefenerfassung zu konfigurieren. Siehe das Beispiel unten.

Ein Promise, das bei Unterstützung des angeforderten Modus und der Funktionen durch Gerät und Benutzer-Agent mit einem XRSession-Objekt aufgelöst wird.

Diese Methode wirft keine echten Ausnahmen; stattdessen wird das zurückgegebene Promise abgelehnt und ein DOMException übergeben, dessen name einer der folgenden ist:

InvalidStateError DOMException

Wird zurückgegeben, wenn der angeforderte Sitzungsmodus immersive-vr ist, aber bereits eine immersive VR-Sitzung entweder aktuell aktiv oder im Aufbau befindet. Es kann nur eine immersive VR-Sitzung gleichzeitig geben.

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 auftreten, wenn eine der erforderlichen Optionen nicht unterstützt wird.

SecurityError DOMException

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

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

anchors

Aktiviert die Verwendung von XRAnchor-Objekten.

bounded-floor

Ähnlich dem Typ local, außer dass der Benutzer nicht außerhalb eines vorgegebenen Bereichs erwartet wird, angegeben durch die boundsGeometry im zurückgegebenen Objekt.

depth-sensing

Ermöglicht die Fähigkeit, Tiefeninformationen über XRDepthInformation-Objekte zu erhalten.

dom-overlay

Ermöglicht das Spezifizieren eines DOM-Overlay-Elements, das dem Benutzer angezeigt wird.

hand-tracking

Ermöglicht die Erfassung von Handbewegungsdaten über handbasierte Eingabesteuerungen (siehe XRHand und XRInputSource.hand).

hit-test

Aktiviert Funktionen für Hit-Tests gegen reale Geometrien.

layers

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

light-estimation

Ermöglicht die Schätzung von Umgebungslichtbedingungen über XRLightEstimate-Objekte.

local

Ermöglicht einen Tracking-Bereich, dessen nativer Ursprung sich in der Nähe der Position des Betrachters zum Zeitpunkt der Sitzungserstellung befindet. Die genaue Position hängt von der zugrunde liegenden Plattform und Implementierung ab. Der Benutzer wird nicht erwartet, sich signifikant von seiner Ausgangsposition zu bewegen, und das Tracking ist für diesen Anwendungsfall optimiert.

local-floor

Ähnlich dem Typ local, außer dass die Ausgangsposition an einem sicheren Ort positioniert ist, um zu stehen, wobei der y-Achsenwert bei 0 auf Bodenhöhe liegt. Wenn diese Bodenhöhe nicht bekannt ist, schätzt der User Agent die Bodenhöhe. Wenn die geschätzte Bodenhöhe nicht null ist, wird vom Browser erwartet, dass er sie so abrundet, dass eine Fingerabdruckerkennung vermieden wird (wahrscheinlich auf den nächsten Zentimeter).

secondary-views

Ermöglicht XRView-Objekte als sekundäre Ansichten. Dies kann für Beobachteransichten aus der ersten Person für Videoaufnahmen oder "Quad-Ansichten" verwendet werden, bei denen es zwei Ansichten pro Auge mit unterschiedlichen Auflösungen und Sichtfeldern gibt.

unbounded

Ermöglicht einen Tracking-Bereich, der dem Benutzer völlige Bewegungsfreiheit erlaubt, möglicherweise über extrem lange Distanzen von seinem Ursprungspunkt. Der Betrachter wird überhaupt nicht verfolgt; das Tracking ist für die Stabilität um die aktuelle Position des Benutzers optimiert, sodass sich der native Ursprung bei Bedarf verschieben kann, um dieses Bedürfnis zu erfüllen.

viewer

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

Mehrere Sitzungsfunktionen und die verschiedenen Referenzräume haben Mindestanforderungen an Sicherheit und Datenschutz, wie das Einholen der Zustimmung des Benutzers und/oder das Erfordernis der Richtlinie Permissions-Policy: xr-spatial-tracking zu setzen. 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, wird eine Sitzung eingerichtet und die Animationsschleife gestartet.

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 sowohl isSessionSupported() als auch requestSession() verwendet werden. Zuerst wird überprü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 Steuerung zum Betreten von XR aktiviert wird. Das Hinzufügen von Steuerelementen ist ein notwendiger Schritt, da das Betreten von XR eine Benutzeraktion erfordert. Schließlich ruft die Methode onButtonClicked() requestSession() auf, wobei dieselbe Sitzungsoption übergeben 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));
  }
}

Ermöglichen Sie eine unbegrenzte Erfahrung, bei der sich der Benutzer 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 zeigt die Präferenz für CPU und "luminance-alpha" an:

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