XRSystem: метод requestSession()

Метод requestSession() интерфейса XRSystem возвращает promise, который разрешается в объект XRSession, с помощью которого можно управлять запрошенным типом сессии WebXR.

Хотя одновременно может быть активна только одна сессия VR, несколько встроенных сессий могут быть в работе одновременно.

mode

Строка String, определяющая режим сессии XR. Поддерживаемые режимы:

• Экспериментально immersive-ar: Вывод сессии получит эксклюзивный доступ к устройству виртуальной реальности, но отображаемое содержимое будет смешиваться с реальной средой. environmentBlendMode сессии указывает метод, используемый для смешивания содержимого.
• immersive-vr: Означает, что отображаемая сессия будет отображаться с помощью устройства XR в режиме VR; она не предназначена для наложения или интеграции в окружающую среду. environmentBlendMode ожидается быть opaque, но может быть additive, если этого требует оборудование.
• inline: Вывод представлен встроенно в контексте элемента в стандартном документе HTML, а не занимает все визуальное пространство. Встроенные сессии могут отображаться в моно- или стереорежиме и могут или не могут иметь отслеживание зрителя. Встроенные сессии не требуют специального оборудования и должны быть доступны на любом агенте пользователя, поддерживающем API WebXR.

options Необязательно

Объект для настройки XRSession. Если ни один не указан, устройство будет использовать конфигурацию по умолчанию для всех параметров.

• requiredFeatures Необязательно: Массив значений, которые обязательно должны поддерживаться возвращаемой XRSession. См. Особенности сессии ниже.
• optionalFeatures Необязательно: Массив значений, определяющих функции, которые возвращаемая XRSession может необязательно поддерживать. См. Особенности сессии ниже.
• domOverlay Необязательно: Объект с обязательным свойством root, которое указывает элемент перекрытия, который будет отображаться пользователю как содержимое перекрытия DOM. См. пример ниже .
• depthSensing Необязательно: Объект с двумя обязательными свойствами usagePreference и dataFormatPreference для настройки выполнения измерения глубины. См. пример ниже .

Объект Promise, который разрешается объектом XRSession, если устройство и пользовательский агент поддерживают запрошенный режим и функции.

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

InvalidStateError DOMException

Возвращается, если запрошенный режим сессии immersive-vr, но уже активна или настраивается сессия виртуальной реальности. Одновременно может быть только одна сессия VR.

NotSupportedError DOMException

Возвращается, если нет доступного устройства, совместимого с WebXR, или устройство не поддерживает указанную sessionMode; это также может быть выброшено, если любая из обязательных опций не поддерживается.

SecurityError DOMException

Возвращается, если разрешение на вход в указанный режим XR отклонено. Это может произойти по нескольким причинам, которые более подробно описаны в Разрешения и безопасность.

Следующие функции и пространства ссылок сессии могут быть запрошены, либо как optionalFeatures или как requiredFeatures.

anchors

Включает использование объектов XRAnchor.

bounded-floor

Аналогично типу local, за исключением того, что пользователю не разрешается перемещаться за пределы предопределенной границы, заданной boundsGeometry в возвращаемом объекте.

depth-sensing

Включает возможность получения информации о глубине с помощью объектов XRDepthInformation.

dom-overlay

Включает возможность указания элемента перекрытия DOM, который будет отображен пользователю.

hand-tracking

Включает информацию об артикулированных позах рук от контроллеров ввода на основе рук (см. XRHand и XRInputSource.hand).

hit-test

Включает функции тестирования попадания для выполнения тестирования попадания в реальную геометрию.

layers

Включает возможность создания различных типов слоев (кроме XRProjectionLayer).

light-estimation

Включает возможность оценки условий освещения окружающей среды с помощью объектов XRLightEstimate.

local

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

local-floor

Аналогично типу local, за исключением того, что начальная позиция размещена в безопасном месте для стояния зрителя, где значение оси y равно 0 на уровне пола. Если этот уровень пола неизвестен, пользовательский агент оценит его. Если оцененный уровень пола не равен нулю, браузер, по ожиданию, округляет его таким образом, чтобы избежать отпечатков пальцев (вероятно, до ближайшего сантиметра).

secondary-views

Включает возможность использования объектов XRView в качестве дополнительных представлений. Это может использоваться для представлений наблюдателя первого лица, используемых для записи видео, или "четырёх представлений", где на каждый глаз приходится два представления с разной разрешающей способностью и полями зрения.

unbounded

Включает пространство отслеживания, которое позволяет пользователю свободно перемещаться, возможно, на очень большие расстояния от исходной точки. Зритель не отслеживается вообще; отслеживание оптимизировано для стабильности вокруг текущего положения пользователя, поэтому родной корень может смещаться по мере необходимости для удовлетворения этой потребности.

viewer

Включает пространство отслеживания, родной корень которого отслеживает положение и ориентацию зрителя.

Несколько функций сеанса и различные пространства ссылок имеют минимальные требования к безопасности и конфиденциальности, такие как запрос согласия пользователя и/или требование Permissions-Policy: xr-spatial-tracking директива должна быть установлена. См. также Разрешения и безопасность для получения более подробной информации.

См. также временную активацию пользователя.

Следующий пример вызывает requestSession(), запрашивая сеанс "immersive-vr". Если Promise разрешается, он настраивает сеанс и инициирует цикл анимации.

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!",
    );
  });

Следующий пример демонстрирует, как использовать как isSessionSupported() , так и requestSession(). Сначала проверяется доступность WebXR, проверяя существование navigator.xr. Затем вызывается isSessionSupported(), передавая ему желаемые параметры сеанса перед включением управления для входа в XR. Добавление управления является необходимым шагом, поскольку вход в XR требует действия пользователя. Наконец, метод onButtonClicked() вызывает requestSession(), используя те же параметры сеанса, что и isSessionSupported().

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));
  }
}

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

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

Здесь вызывающий метод может обрабатывать как использование, оптимизированное для ЦП, так и для графического процессора, а также форматы «luminance-alpha» и «float32». Порядок указывает предпочтение ЦП и «luminance-alpha»:

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