Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
WebXRInterface
Eredita: XRInterface < RefCounted < Object
Interfaccia XR che utilizza WebXR.
Descrizione
WebXR è uno standard aperto che consente di creare applicazioni VR e AR che vengono eseguite nel browser Web.
Di conseguenza, questa interfaccia è disponibile solo quando è in esecuzione nelle esportazioni Web.
WebXR supporta un'ampia gamma di dispositivi, da quelli molto avanzati (come Valve Index, HTC Vive, Oculus Rift e Quest) a quelli molto meno avanzati (come Google Cardboard, Oculus Go, GearVR o semplici smartphone).
Poiché WebXR è basato su JavaScript, fa ampio uso di callback, il che significa che WebXRInterface è costretta a utilizzare segnali, mentre altre interfacce XR utilizzerebbero invece funzioni che restituiscono immediatamente un risultato. Ciò rende WebXRInterface un po' più complicata da inizializzare rispetto ad altre interfacce XR.
Ecco il codice minimo necessario per avviare una sessione di VR immersiva:
extends Node3D
var webxr_interface
var vr_supported = false
func _ready():
# Supponiamo che questo nodo abbia un pulsante come figlio.
# Questo pulsante serve all'utente per entrare in modalità VR immersiva.
$Button.pressed.connect(self._on_button_pressed)
webxr_interface = XRServer.find_interface("WebXR")
if webxr_interface:
# WebXR utilizza molti callback asincroni, quindi ci colleghiamo a vari
# segnali per riceverli.
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)
# Questo restituisce immediatamente: il nostro metodo _webxr_session_supported()
# (che abbiamo connesso al segnale "session_supported" precedente)
# verrà chiamato in seguito per farci sapere se è supportato o meno.
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("Il tuo browser non supporta il VR")
return
# Vogliamo una sessione VR immersiva, invece di AR ('immersive-ar') o un
# semplice visore 3DoF ('viewer').
webxr_interface.session_mode = 'immersive-vr'
# 'bounded-floor' è la scala della stanza, 'local-floor' è un'esperienza in piedi o seduti
# (ti posiziona a 1,6 m dal suolo se hai un visore 3DoF),
# mentre 'local' ti posiziona giù all'XROrigin.
# Questa lista significa che proverà prima a richiedere 'bounded-floor', quindi
# ricadrà su 'local-floor' e infine 'local', se non è supportato
# altro.
webxr_interface.requested_reference_space_types = 'bounded-floor, local-floor, local'
# Per usare 'local-floor' o 'bounded-floor' dobbiamo anche
# contrassegnare le funzionalità come obbligatorie o facoltative. Includendo 'hand-tracking'
# come funzionalità facoltativa, verrà abilitato se supportato.
webxr_interface.required_features = 'local-floor'
webxr_interface.optional_features = 'bounded-floor, hand-tracking'
# Questo restituirà false se non siamo in grado di richiedere la sessione,
# tuttavia, può comunque fallire in modo asincrono più avanti nel processo, quindi
# sappiamo solo se è riuscito o meno quando vengono chiamati i nostri
# metodi _webxr_session_started() o _webxr_session_failed().
if not webxr_interface.initialize():
OS.alert("Impossibile inizializzare")
return
func _webxr_session_started():
$Button.visible = false
# Questo dice a Godot di iniziare a renderizzare sul visore.
get_viewport().use_xr = true
#Questo sarà il tipo di spazio di riferimento che hai ottenuto alla fine, tra i
# tipi che hai richiesto in precedenza. Questo è utile se vuoi che il gioco
# funzioni in modo leggermente diverso in 'bounded-floor' rispetto a 'local-floor'.
print("Tipo dello spazio di riferimento: ", webxr_interface.reference_space_type)
# Questo sarà la lista delle funzionalità che sono state abilitate con successo
# (tranne nei browser che non supportano questa proprietà).
print("Funzionalità abilitate: ", webxr_interface.enabled_features)
func _webxr_session_ended():
$Button.visible = true
# Se l'utente esce dalla modalità immersiva, allora diciamo a Godot
# di renderizzare nuovamente la pagina web.
get_viewport().use_xr = false
func _webxr_session_failed(message):
OS.alert("Impossibile inizializzare: " + message)
Ci sono un paio di modi per gestire l'input dai "controller":
Attraverso i nodi XRController3D e i loro segnali XRController3D.button_pressed e XRController3D.button_released. Questo è il modo in cui i controller sono solitamente gestiti nelle applicazioni XR in Godot, tuttavia, questo funzionerà solo con controller VR avanzati, come i controller di Oculus Touch o di Index, ad esempio.
Attraverso select, squeeze e i segnali correlati. Questo metodo funzionerà sia per i controller VR avanzati sia per le sorgenti di input non tradizionali come un tocco sullo schermo, un comando vocale parlato o la pressione di un pulsante sul dispositivo stesso.
È possibile usare entrambi i modi per consentire al proprio gioco o alla propria applicazione di supportare un più meno dispositivi e metodi di input, o per permettere interazioni più avanzate con i dispositivi più avanzati.
Tutorial
Proprietà
Metodi
get_display_refresh_rate() const |
|
get_input_source_target_ray_mode(input_source_id: int) const |
|
get_input_source_tracker(input_source_id: int) const |
|
is_input_source_active(input_source_id: int) const |
|
void |
is_session_supported(session_mode: String) |
void |
set_display_refresh_rate(refresh_rate: float) |
Segnali
display_refresh_rate_changed() 🔗
Emesso dopo che la frequenza di aggiornamento del display è cambiata.
reference_space_reset() 🔗
Emesso per indicare che lo spazio di riferimento è stato reimpostato o riconfigurato.
Quando (o se) questo viene emesso dipende dal browser o dal dispositivo dell'utente, ma può includere quando l'utente ha modificato le dimensioni del proprio spazio di gioco (a cui potresti accedere tramite XRInterface.get_play_area()) o ha premuto/trattenuto un pulsante per ricentrare la sua posizione.
Consulta Evento di reimpostazione XRReferenceSpace di WebXR per ulteriori informazioni.
select(input_source_id: int) 🔗
Emesso dopo che una delle sorgenti di input ha terminato la sua "azione primaria".
Usa get_input_source_tracker() e get_input_source_target_ray_mode() per ottenere ulteriori informazioni sulla sorgente di input.
selectend(input_source_id: int) 🔗
Emesso quando una delle sorgenti di input ha terminato la sua "azione primaria".
Usa get_input_source_tracker() e get_input_source_target_ray_mode() per ottenere ulteriori informazioni sulla sorgente di input.
selectstart(input_source_id: int) 🔗
Emesso dopo che una delle sorgenti di input ha cominciato la sua "azione primaria".
Usa get_input_source_tracker() e get_input_source_target_ray_mode() per ottenere ulteriori informazioni sulla sorgente di input.
session_ended() 🔗
Emesso quando l'utente termina la sessione WebXR (operazione che può essere eseguita tramite l'interfaccia utente del browser o del dispositivo).
A questo punto, dovresti eseguire get_viewport().use_xr = false per indicare a Godot di riprendere il rendering sullo schermo.
session_failed(message: String) 🔗
Emesso da XRInterface.initialize() se la sessione non riesce ad avviarsi.
message può facoltativamente contenere un messaggio di errore da WebXR o una stringa vuota se nessun messaggio è disponibile.
session_started() 🔗
Emesso da XRInterface.initialize() se la sessione è stata avviata correttamente.
A questo punto, è sicuro eseguire get_viewport().use_xr = true per istruire Godot ad avviare il rendering sul dispositivo XR.
session_supported(session_mode: String, supported: bool) 🔗
Emesso da is_session_supported() per indicare se la modalità di sessione session_mode specificato è supportato o meno.
squeeze(input_source_id: int) 🔗
Emesso dopo che una delle sorgenti di input ha terminato la sua "azione di compressione primaria".
Usa get_input_source_tracker() e get_input_source_target_ray_mode() per ottenere ulteriori informazioni sulla sorgente di input.
squeezeend(input_source_id: int) 🔗
Emesso quando una delle sorgenti di input ha terminato la sua "azione di compressione primaria".
Usa get_input_source_tracker() e get_input_source_target_ray_mode() per ottenere ulteriori informazioni sulla sorgente di input.
squeezestart(input_source_id: int) 🔗
Emesso quando una delle sorgenti di input ha cominciato la sua "azione di compressione primaria".
Usa get_input_source_tracker() e get_input_source_target_ray_mode() per ottenere ulteriori informazioni sulla sorgente di input.
visibility_state_changed() 🔗
Emesso quando visibility_state è cambiato.
Enumerazioni
enum TargetRayMode: 🔗
TargetRayMode TARGET_RAY_MODE_UNKNOWN = 0
Non conosciamo la modalità del raggio di destinazione.
TargetRayMode TARGET_RAY_MODE_GAZE = 1
Il raggio di destinazione ha origine dagli occhi dell'osservatore e punta nella direzione in cui sta guardando.
TargetRayMode TARGET_RAY_MODE_TRACKED_POINTER = 2
Il raggio di destinazione ha origine da un puntatore portatile, molto probabilmente un controller touch VR.
TargetRayMode TARGET_RAY_MODE_SCREEN = 3
Il raggio di destinazione ha origine dal touch screen, il mouse o un altro dispositivo di input tattile.
Descrizioni delle proprietà
String get_enabled_features()
Un elenco separato da virgole di funzionalità che sono state abilitate correttamente da XRInterface.initialize() durante la configurazione della sessione WebXR.
Questo può includere funzionalità richieste impostando required_features e optional_features e sarà disponibile solo dopo l'emissione di session_started.
Nota: Questo potrebbe non essere supportato da tutti i browser Web, nel qual caso sarà una stringa vuota.
Un elenco separato da virgole di funzionalità opzionali utilizzate da XRInterface.initialize() durante la configurazione della sessione WebXR.
Se il browser o il dispositivo di un utente non supporta una delle funzionalità fornite, l'inizializzazione continuerà, ma non sarà possibile utilizzare la funzionalità richiesta.
Ciò non ha alcun effetto sull'interfaccia quando è già inizializzata.
Consultare la documentazione MDN sulle funzionalità di sessione WebXR per una lista di possibili valori.
String get_reference_space_type()
Il tipo di spazio di riferimento (dall'elenco dei tipi richiesti impostato nella proprietà requested_reference_space_types), che è stato infine utilizzato da XRInterface.initialize() durante la configurazione della sessione WebXR.
I valori possibili provengono da XRReferenceSpaceType di WebXR. Se si desidera utilizzare un particolare tipo di spazio di riferimento, deve essere elencato in required_features o optional_features.
String requested_reference_space_types 🔗
void set_requested_reference_space_types(value: String)
String get_requested_reference_space_types()
Un elenco separato da virgole di tipi di spazio di riferimento utilizzati da XRInterface.initialize() durante la configurazione della sessione WebXR.
I tipi di spazio di riferimento sono richiesti in ordine, e sarà utilizzato il primo supportato dal dispositivo o dal browser dell'utente. La proprietà reference_space_type contiene il tipo di spazio di riferimento che è stato infine selezionato.
Ciò non ha alcun effetto sull'interfaccia quando è già inizializzata.
I valori possibili provengono da XRReferenceSpaceType di WebXR. Se si desidera utilizzare un particolare tipo di spazio di riferimento, deve essere elencato in required_features o optional_features.
Un elenco separato da virgole delle funzionalità richieste utilizzate da XRInterface.initialize() durante la configurazione della sessione WebXR.
Se il browser o il dispositivo di un utente non supporta una delle funzionalità fornite, l'inizializzazione fallirà e verrà emesso session_failed.
Ciò non ha alcun effetto sull'interfaccia quando è già inizializzata.
Consultare la documentazione MDN sulle funzionalità di sessione WebXR per una lista di possibili valori.
La modalità di sessione utilizzata da XRInterface.initialize() quando si imposta la sessione WebXR.
Non ha alcun effetto sull'interfaccia quando è già inizializzata.
I valori possibili provengono da XRSessionMode di WebXR, tra cui: "immersive-vr", "immersive-ar" e "inline".
String get_visibility_state()
Indica se le immagini della sessione WebXR sono visibili all'utente.
I valori possibili provengono da XRVisibilityState di WebXR, inclusi "hidden", "visible" e "visible-blurred".
Descrizioni dei metodi
Array get_available_display_refresh_rates() const 🔗
Restituisce le frequenze di aggiornamento del display supportate dall'HMD corrente. Restituito solo se questa funzionalità è supportata dal browser Web e dopo che l'interfaccia è stata inizializzata.
float get_display_refresh_rate() const 🔗
Restituisce la frequenza di aggiornamento del display per l'HMD attuale. Non supportato su tutti gli HMD e browser. Potrebbe non riportare un valore accurato fino a dopo aver usato set_display_refresh_rate().
TargetRayMode get_input_source_target_ray_mode(input_source_id: int) const 🔗
Restituisce la modalità raggio di destinazione per la sorgente di input input_source_id.
Questo può aiutare a interpretare l'input proveniente da quella sorgente di input. Consulta XRInputSource.targetRayMode per ulteriori informazioni.
XRControllerTracker get_input_source_tracker(input_source_id: int) const 🔗
Ottiene un XRControllerTracker per il la sorgente di input input_source_id.
Nel contesto di WebXR, una sorgente di input può essere un controller VR avanzato come i controller Oculus Touch o Index, o anche un tocco sullo schermo, un comando vocale pronunciato o la pressione di un pulsante sul dispositivo stesso. Quando viene utilizzata una sorgente di input non tradizionale, interpreta la posizione e l'orientamento di XRPositionalTracker come un raggio che punta all'oggetto con cui l'utente desidera interagire.
Usa questo metodo per ottenere informazioni sulla sorgente di input che ha attivato uno di questi segnali:
bool is_input_source_active(input_source_id: int) const 🔗
Restituisce true se è presente una sorgente di input attiva con l'input_source_id fornito.
void is_session_supported(session_mode: String) 🔗
Verifica se la modalità di sessione session_mode è supportata dal browser dell'utente.
I valori possibili provengono da XRSessionMode di WebXR, tra cui: "immersive-vr", "immersive-ar" e "inline".
Questo metodo non restituisce nulla, invece emette il segnale session_supported con il risultato.
void set_display_refresh_rate(refresh_rate: float) 🔗
Imposta la frequenza di aggiornamento del display per l'HMD corrente. Non supportato su tutti gli HMD e browser. Non avrà effetto immediato finché non verrà emesso display_refresh_rate_changed.