WebGLRenderingContext: makeXRCompatible() Methode

Syntax

makeXRCompatible()

Parameter

Es gibt keine Parameter.

Rückgabewert

Ein Promise, das erfolgreich aufgelöst wird, sobald der WebGL-Kontext bereit ist, um WebXR Inhalte zu rendern.

Ausnahmen

Diese Methode wirft keine traditionellen Ausnahmen; stattdessen wird das Promise mit einem der folgenden Fehler abgelehnt, der als Wert an den Ablehnungs-Handler übergeben wird:

AbortError DOMException

Wird zurückgegeben, wenn das Umschalten des Kontexts auf einen WebXR-kompatiblen Kontext fehlschlägt.

InvalidStateError DOMException

Wird zurückgegeben, wenn der WebGL-Kontext verloren gegangen ist oder kein WebXR-Gerät verfügbar ist.

Nutzungshinweise

Da makeXRCompatible() möglicherweise den zugrunde liegenden WebGL-Kontext mit einem neuen ersetzt, der die neue Rendering-Hardware verwendet, können die vorhandenen Inhalte des Kontexts verloren gehen und müssten neu gerendert werden. Aus diesem Grund werden die Ereignisse webglcontextlost und webglcontextrestored verwendet: Das erste gibt Ihnen die Möglichkeit, alles zu verwerfen, was Sie nicht mehr benötigen, während das zweite Ihnen die Möglichkeit gibt, Ressourcen zu laden und die Szene im neuen Kontext vorzubereiten.

Obwohl diese Methode über das WebGLRenderingContext Interface verfügbar ist, wird sie tatsächlich von der WebXR Device API definiert und nicht von WebGL.

Beispiele

Dieses Beispiel demonstriert eine mögliche Logik in einem Spiel, das mit WebGL gestartet wird, um Menüs und andere Benutzeroberflächen anzuzeigen, und WebGL verwendet, um das Gameplay zu rendern. Es gibt allerdings einen Button im Hauptmenü, der eine Option bietet, das Spiel im WebXR-Modus zu starten.

HTML

Der HTML-Code für die Buttons sieht folgendermaßen aus:

<button class="green button" type="button">Start Game</button>
<button class="blue button use-webxr" type="button">
  Start Game (VR mode)
</button>

Der erste Button startet das Spiel und präsentiert es weiterhin wie gewohnt auf dem Bildschirm. Der zweite Button wird verwendet, um das Spiel im immersive-vr Modus zu starten. Beachten Sie die Einbeziehung der Klasse use-webxr auf dem VR-Modus-Button. Dies ist wichtig, worauf wir gleich noch näher eingehen werden.

JavaScript

Der Code, der das Starten der Grafik, das Umschalten in den VR-Modus und so weiter behandelt, sieht folgendermaßen aus:

const outputCanvas = document.querySelector(".output-canvas");
const gl = outputCanvas.getContext("webgl");
let xrSession = null;
let usingXR = false;
let currentScene = "scene1";
let glStartButton;
let xrStartButton;

loadSceneResources(currentScene);

glStartButton.addEventListener("click", handleStartButtonClick);
xrStartButton.addEventListener("click", handleStartButtonClick);

outputCanvas.addEventListener("webglcontextlost", (event) => {
  /* The context has been lost but can be restored */
  event.canceled = true;
});

/* When the GL context is reconnected, reload the resources for the
   current scene. */
outputCanvas.addEventListener("webglcontextrestored", (event) => {
  loadSceneResources(currentScene);
});

async function onStartedXRSession(xrSession) {
  try {
    await gl.makeXRCompatible();
  } catch (err) {
    switch (err) {
      case AbortError:
        showSimpleMessageBox(
          "Unable to transfer the game to your XR headset.",
          "Cancel",
        );
        break;
      case InvalidStateError:
        showSimpleMessageBox(
          "You don't appear to have a compatible XR headset available.",
          "Cancel",
        );
        break;
      default:
        handleFatalError(err);
        break;
    }
    xrSession.end();
  }
}

async function handleStartButtonClick(event) {
  if (event.target.classList.contains("use-webxr") && navigator.xr) {
    try {
      xrSession = await navigator.xr.requestSession("immersive-vr");
      usingXR = true;
    } catch (err) {
      xrSession = NULL;
      usingXR = false;
    }
  }
  startGame();
}

function startGame() {
  currentScene = "scene1";
  loadSceneResources(currentScene);

  /* and so on */
}

Das funktioniert, indem zwei Buttons vorhanden sind, von denen einer das Spiel normal startet und der andere das Spiel im VR-Modus startet. Beide verwenden die Funktion handleStartButtonClick() als ihren Ereignis-Handler. Die Funktion bestimmt, dass der angeklickte Button derjenige ist, der den immersive-vr Modus anfordert, indem überprüft wird, ob der Button die Klasse use-webxr hat. Wenn der vom Benutzer angeklickte Button diese Klasse hat (und wir bestätigt haben, dass WebXR verfügbar ist, indem wir sicherstellen, dass die navigator.xr Eigenschaft existiert), verwenden wir requestSession() um eine neue WebXR-Sitzung anzufordern und setzen das usingXR Flag auf true.

Wenn der andere Button geklickt wurde, stellen wir sicher, dass xrSession NULL ist und löschen usingXR indem wir es auf false setzen.

Dann wird die startGame() Funktion aufgerufen, um den Beginn des Spiels auszulösen.

Es werden Handler für sowohl webglcontextlost als auch webglcontextrestored bereitgestellt; im ersten Fall stellen wir sicher, dass wir wissen, dass der Zustand wiederhergestellt werden kann, während wir im zweiten Fall tatsächlich die Szene neu laden, um sicherzustellen, dass wir die korrekten Ressourcen für die aktuelle Bildschirm- oder Headset-Konfiguration haben.

Spezifikationen

Browser-Kompatibilität