WebXRInterface

Наследует: XRInterface < RefCounted < Object

Интерфейс XR с использованием WebXR.

Описание

WebXR — это открытый стандарт, позволяющий создавать приложения VR и AR, работающие в веб-браузере.

Таким образом, этот интерфейс доступен только при работе в веб-экспорте.

WebXR поддерживает широкий спектр устройств, от очень мощных (например, Valve Index, HTC Vive, Oculus Rift и Quest) до гораздо менее мощных (например, Google Cardboard, Oculus Go, GearVR или простые смартфоны).

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

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

extends Node3D

var webxr_interface
var vr_supported = false

func _ready():
    # Мы предполагаем, что этот узел имеет кнопку в качестве дочернего элемента.
    # Эта кнопка позволяет пользователю дать согласие на вход в режим погружения в виртуальную реальность.
    $Button.pressed.connect(self._on_button_pressed)

    webxr_interface = XRServer.find_interface("WebXR")
    if webxr_interface:
        # WebXR использует много асинхронных обратных вызовов, поэтому мы подключаемся к различным
        # сигналам для их приема.
        webxr_interface.session_supported.connect(self._webxr_session_supported)
        webxr_interface.session_started.connect(self._webxr_session_started)
        webxr_interface.session_ended.connect(self._webxr_session_ended)
        webxr_interface.session_failed.connect(self._webxr_session_failed)

        # Это возвращает немедленно - наш метод _webxr_session_supported()
        # (который мы подключили к сигналу "session_supported" выше) будет
        # вызван позже, чтобы сообщить нам, поддерживается он или нет.
        webxr_interface.is_session_supported("immersive-vr")

func _webxr_session_supported(session_mode, supported):
    if session_mode == 'immersive-vr':
        vr_supported = supported

func _on_button_pressed():
    if not vr_supported:
        OS.alert("Ваш браузер не поддерживает VR")
        return

    # Мы хотим сеанс погружения в виртуальную реальность, а не в дополненную реальность ('immersive-ar') или
    # простое средство просмотра 3DoF ('viewer').
    webxr_interface.session_mode = 'immersive-vr'
    # «bounded-floor» — масштаб комнаты, «local-floor» — опыт стоя
    # или сидя (при наличии гарнитуры 3DoF вы оказываетесь на высоте 1,6 м над землей),
    # в то время как «local» помещает вас в XROrigin.
    # Этот список означает, что сначала будет предпринята попытка запросить «bounded-floor»,
    # затем будет выполнен возврат к «local-floor» и, в конечном итоге, «local», если ничего другого
    # не поддерживается.
    webxr_interface.requested_reference_space_types = 'bounded-floor, local-floor, local'
    # Чтобы использовать 'local-floor' или 'bounded-floor', мы также должны
    # пометить функции как обязательные или необязательные. Включив 'hand-tracking'
    # как необязательную функцию, она будет включена, если поддерживается.
    webxr_interface.required_features = 'local-floor'
    webxr_interface.optional_features = 'bounded-floor, hand-tracking'

    # Это вернет false, если мы даже не сможем запросить сеанс,
    # однако, он все еще может асинхронно завершиться неудачей позже в процессе, поэтому мы
    # узнаем, действительно ли он был успешным или неудачным, только когда вызываются наши
    # методы _webxr_session_started() или _webxr_session_failed().
    if not webxr_interface.initialize():
        OS.alert("Не удалось инициализировать")
        return

func _webxr_session_started():
    $Button.visible = false
    # Это дает команду Godot начать рендеринг на гарнитуре.
    get_viewport().use_xr = true
    # Это будет тип опорного пространства, который вы в конечном итоге получили из
    # типов, которые вы запросили выше. Это полезно, если вы хотите, чтобы игра
    # работала немного по-разному в 'bounded-floor' и 'local-floor'.
    print("Тип референса пространства: ", webxr_interface.reference_space_type)
    # Это будет список функций, которые были успешно включены
    # (за исключением браузеров, которые не поддерживают это свойство).
    print("Включенные функции: ", webxr_interface.enabled_features)

func _webxr_session_ended():
    $Button.visible = true
    # Если пользователь выходит из режима погружения, мы говорим Godot снова
    # отобразить веб-страницу.
    get_viewport().use_xr = false

func _webxr_session_failed(message):
    OS.alert("Не удалось инициализировать: " + message)

Есть несколько способов обработки ввода «контроллера»:

  • Использование узлов XRController3D и их сигналов XRController3D.button_pressed и XRController3D.button_released. Так обычно обрабатываются контроллеры в приложениях XR в Godot, однако это будет работать только с продвинутыми контроллерами VR, такими как контроллеры Oculus Touch или Index, например.

  • Использование сигналов select, squeeze и связанных с ними сигналов. Этот метод будет работать как для продвинутых контроллеров VR, так и для нетрадиционных источников ввода, таких как нажатие на экран, голосовая команда или нажатие кнопки на самом устройстве.

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

Обучающие материалы

Свойства

String

enabled_features

String

optional_features

String

reference_space_type

String

requested_reference_space_types

String

required_features

String

session_mode

String

visibility_state

Методы

Array

get_available_display_refresh_rates() const

float

get_display_refresh_rate() const

TargetRayMode

get_input_source_target_ray_mode(input_source_id: int) const

XRControllerTracker

get_input_source_tracker(input_source_id: int) const

bool

is_input_source_active(input_source_id: int) const

void

is_session_supported(session_mode: String)

void

set_display_refresh_rate(refresh_rate: float)

Сигналы

display_refresh_rate_changed() 🔗

Возникает после изменения частоты обновления дисплея.

reference_space_reset() 🔗

Вызывается для указания на то, что ссылочное пространство было сброшено или перенастроено.

Когда (и будет ли) это срабатывать, зависит от браузера или устройства пользователя, но может включать в себя, когда пользователь изменил размеры своего игрового пространства (к которому вы можете получить доступ через XRInterface.get_play_area()) или нажал/удержал кнопку для рецентрирования своего положения.

См. WebXR's XRReferenceSpace событие сброса для получения дополнительной информации.

select(input_source_id: int) 🔗

Выдается после того, как один из источников ввода завершил свое «основное действие».

Используйте get_input_source_tracker() и get_input_source_target_ray_mode(), чтобы получить больше информации об источнике ввода.

selectend(input_source_id: int) 🔗

Выдается, когда один из источников ввода завершил свое «основное действие».

Используйте get_input_source_tracker() и get_input_source_target_ray_mode(), чтобы получить больше информации об источнике ввода.

selectstart(input_source_id: int) 🔗

Выдается, когда один из источников ввода начал свое «основное действие».

Используйте get_input_source_tracker() и get_input_source_target_ray_mode(), чтобы получить больше информации об источнике ввода.

session_ended() 🔗

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

В этот момент вам следует выполнить get_viewport().use_xr = false, чтобы указать Godot возобновить рендеринг на экране.

session_failed(message: String) 🔗

Выдается XRInterface.initialize(), если сеанс не запускается.

message может содержать сообщение об ошибке от WebXR или пустую строку, если сообщение отсутствует.

session_started() 🔗

Выдается XRInterface.initialize(), если сеанс успешно запущен.

На этом этапе можно безопасно выполнить get_viewport().use_xr = true, чтобы указать Godot начать рендеринг на устройстве XR.

session_supported(session_mode: String, supported: bool) 🔗

Создается is_session_supported() для указания того, поддерживается ли заданный session_mode или нет.

squeeze(input_source_id: int) 🔗

Выдается после того, как один из источников ввода завершил свое «основное действие сжатия».

Используйте get_input_source_tracker() и get_input_source_target_ray_mode(), чтобы получить больше информации об источнике ввода.

squeezeend(input_source_id: int) 🔗

Выдается, когда один из источников ввода завершил свое «основное действие сжатия».

Используйте get_input_source_tracker() и get_input_source_target_ray_mode(), чтобы получить больше информации об источнике ввода.

squeezestart(input_source_id: int) 🔗

Выдается, когда один из источников ввода начал свое «основное действие сжатия».

Используйте get_input_source_tracker() и get_input_source_target_ray_mode(), чтобы получить больше информации об источнике ввода.

visibility_state_changed() 🔗

Вызывается при изменении visible_state.

Перечисления

enum TargetRayMode: 🔗

TargetRayMode TARGET_RAY_MODE_UNKNOWN = 0

Мы не знаем целевой режим луча.

TargetRayMode TARGET_RAY_MODE_GAZE = 1

Луч цели исходит из глаз наблюдателя и указывает в направлении его взгляда.

TargetRayMode TARGET_RAY_MODE_TRACKED_POINTER = 2

Направляет луч от портативной указки, скорее всего, сенсорного контроллера виртуальной реальности.

TargetRayMode TARGET_RAY_MODE_SCREEN = 3

Направляет луч с сенсорного экрана, мыши или другого тактильного устройства ввода.

Описания свойств

String enabled_features 🔗

  • String get_enabled_features()

Разделенный запятыми список функций, которые были успешно включены XRInterface.initialize() при настройке сеанса WebXR.

Сюда могут входить функции, запрошенные путем установки required_features и Optional_features, и будут доступны только после отправки session_started.

Примечание: Это может не поддерживаться всеми веб-браузерами, в этом случае это будет пустая строка.

String optional_features 🔗

  • void set_optional_features(value: String)

  • String get_optional_features()

Список дополнительных функций, разделённых запятыми, используемых XRInterface.initialize() при настройке сеанса WebXR.

Если браузер или устройство пользователя не поддерживает одну из указанных функций, инициализация будет продолжена, но запрошенная функция будет недоступна.

Это никак не повлияет на интерфейс, если он уже инициализирован.

Список возможных значений см. в документации MDN о функциях сеанса WebXR.

String reference_space_type 🔗

  • String get_reference_space_type()

Тип пространства ссылок (из списка запрошенных типов, установленных в свойстве asked_reference_space_types), который в конечном итоге использовался XRInterface.initialize() при настройке сеанса WebXR.

Возможные значения берутся из WebXR's XRReferenceSpaceType. Если вы хотите использовать определенный тип пространства ссылок, он должен быть указан либо в required_features, либо в Optional_features.

String requested_reference_space_types 🔗

  • void set_requested_reference_space_types(value: String)

  • String get_requested_reference_space_types()

Список типов ссылочных пространств, разделённых запятыми, используемых методом XRInterface.initialize() при настройке сеанса WebXR.

Типы ссылочных пространств запрашиваются по порядку, и будет использоваться первый тип, поддерживаемый устройством или браузером пользователя. Свойство reference_space_type содержит выбранный тип ссылочного пространства.

Это не влияет на интерфейс, если он уже инициализирован.

Возможные значения берутся из WebXR's XRReferenceSpaceType. Если вы хотите использовать определённый тип ссылочного пространства, он должен быть указан либо в required_features, либо в optional_features.

String required_features 🔗

  • void set_required_features(value: String)

  • String get_required_features()

Разделённый запятыми список обязательных функций, используемых XRInterface.initialize() при настройке сеанса WebXR.

Если браузер или устройство пользователя не поддерживает одну из указанных функций, инициализация завершится ошибкой и будет выдан сигнал session_failed.

Это никак не повлияет на интерфейс, если он уже инициализирован.

Список возможных значений см. в документации MDN о функциях сеанса WebXR.

String session_mode 🔗

  • void set_session_mode(value: String)

  • String get_session_mode()

Режим сеанса, используемый XRInterface.initialize() при настройке сеанса WebXR.

Это не оказывает никакого влияния на интерфейс, если он уже инициализирован.

Возможные значения берутся из WebXR's XRSessionMode, включая: "immersive-vr", "immersive-ar" и "inline".

String visibility_state 🔗

  • String get_visibility_state()

Указывает, видны ли пользователю изображения сеанса WebXR.

Возможные значения берутся из WebXR XRVisibilityState, включая "hidden", "visible" и "visible-blurred".

Описания метода

Array get_available_display_refresh_rates() const 🔗

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

float get_display_refresh_rate() const 🔗

Возвращает частоту обновления дисплея для текущего HMD. Поддерживается не всеми HMD и браузерами. Может не сообщать точное значение до использования set_display_refresh_rate().

TargetRayMode get_input_source_target_ray_mode(input_source_id: int) const 🔗

Возвращает режим целевого луча для заданного input_source_id.

Это может помочь интерпретировать ввод, поступающий из этого источника ввода. Для получения дополнительной информации см. XRInputSource.targetRayMode.

XRControllerTracker get_input_source_tracker(input_source_id: int) const 🔗

Получает XRControllerTracker для заданного input_source_id.

В контексте WebXR источником ввода может быть усовершенствованный контроллер VR, такой как контроллеры Oculus Touch или Index, или даже нажатие на экран, произнесенная голосовая команда или нажатие кнопки на самом устройстве. При использовании нетрадиционного источника ввода интерпретируйте положение и ориентацию XRPositionalTracker как луч, указывающий на объект, с которым пользователь хочет взаимодействовать.

Используйте этот метод, чтобы получить информацию об источнике ввода, который вызвал один из этих сигналов:

bool is_input_source_active(input_source_id: int) const 🔗

Возвращает true, если есть активный источник ввода с указанным input_source_id.

void is_session_supported(session_mode: String) 🔗

Проверяет, поддерживается ли заданный session_mode браузером пользователя.

Возможные значения берутся из WebXR's XRSessionMode, включая: "immersive-vr", "immersive-ar" и "inline".

Этот метод ничего не возвращает, вместо этого он выдает сигнал session_supported с результатом.

void set_display_refresh_rate(refresh_rate: float) 🔗

Устанавливает частоту обновления дисплея для текущего HMD. Поддерживается не всеми HMD и браузерами. Вступит в силу не сразу, пока не будет выдан display_refresh_rate_changed.