WebGLRenderingContext: метод makeXRCompatible()

Метод WebGLRenderingContext makeXRCompatible() гарантирует, что контекст отрисовки, описанный WebGLRenderingContext, готов к отрисовке сцены для устройства с поддержкой технологии погружения WebXR, на котором он будет отображаться. При необходимости, слой WebGL может переконфигурировать контекст, чтобы он был готов к отрисовке на устройстве, отличном от первоначального.

Это полезно, если у вас приложение, которое изначально отображается на стандартном 2D экране, но затем может переключаться на 3D систему погружения.

Нет.

Promise обещание, которое успешно выполняется, как только контекст WebGL готов для отрисовки контента WebXR.

Этот метод не генерирует традиционные исключения; вместо этого обещание отклоняется с одним из следующих ошибок, переданных в обработчик отклонения:

AbortError DOMException

Возвращается, если переключение контекста на WebXR-совместимый контекст завершилось неудачно.

InvalidStateError DOMException

Возвращается, если контекст WebGL потерян или нет доступного устройства WebXR.

Так как makeXRCompatible() может включать в себя замену основного контекста WebGL новым, использующим новое оборудование для отрисовки, существующее содержимое контекста может быть потеряно и, следовательно, потребуется повторная отрисовка. Вот почему используются события webglcontextlost и webglcontextrestored: первое предоставляет возможность избавиться от ненужного содержимого, а второе — возможность загрузить ресурсы и подготовиться к отрисовке сцены в новом контексте.

Хотя этот метод доступен через интерфейс WebGLRenderingContext, он фактически определён в API устройств WebXR, а не в WebGL.

Этот пример демонстрирует логику кода, которую вы можете найти в игре, которая начинает работать с использованием WebGL для отображения меню и других элементов пользовательского интерфейса, а затем использует WebGL для отрисовки игрового процесса, но имеет кнопку в главном меню, которая предлагает возможность запустить игру в режиме WebXR.

HTML для кнопок выглядит так:

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

Первая кнопка запускает игру, продолжая отображать её на экране, как обычно. Вторая кнопка будет использоваться для запуска игры в режиме immersive-vr. Обратите внимание на включение класса use-webxr на кнопке режима VR. Это важно, и мы рассмотрим это далее.

Код, который обрабатывает запуск графики, переключение на режим VR и так далее, выглядит так:

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

window.addEventListener("load", (event) => {
  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 */
}

Это работает путём наличия двух кнопок: одной, которая запускает игру обычно, и другой, которая запускает игру в режиме VR. Обе они используют функцию handleStartButtonClick() в качестве обработчика событий. Функция определяет, что нажата кнопка, запрашивающая режим immersive-vr, проверяя, есть ли у кнопки класс use-webxr. Если нажатая кнопка имеет этот класс (и мы подтвердили, что WebXR доступен, убедившись в существовании свойства navigator.xr), мы используем requestSession() для запроса новой сессии WebXR и устанавливаем флаг usingXR в значение true.

Если была нажата другая кнопка, мы убеждаемся, что xrSession имеет значение NULL и очищаем usingXR до значения false.

Затем вызывается функция startGame() для запуска игрового процесса.

Предоставляются обработчики для событий webglcontextlost и webglcontextrestored; в первом случае мы убеждаемся, что состояние можно восстановить, а во втором — фактически перезагружаем сцену, чтобы убедиться, что у нас есть правильные ресурсы для текущей конфигурации экрана или гарнитуры.