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...
OpenXRExtensionWrapper
Eredita: Object
Ereditato da: OpenXRAndroidThreadSettingsExtension, OpenXRExtensionWrapperExtension, OpenXRFrameSynthesisExtension, OpenXRFutureExtension, OpenXRRenderModelExtension, OpenXRSpatialAnchorCapability, OpenXRSpatialEntityExtension, OpenXRSpatialMarkerTrackingCapability, OpenXRSpatialPlaneTrackingCapability
Consente di implementare estensioni OpenXR con GDExtension.
Descrizione
OpenXRExtensionWrapper allows implementing OpenXR extensions with GDExtension. The extension should be registered with register_extension_wrapper().
When OpenXRInterface is initialized as the primary interface and any Viewport has Viewport.use_xr set to true, OpenXR will become involved in Godot's rendering process. If ProjectSettings.rendering/driver/threads/thread_model is set to "Separate", Godot's renderer will run on its own thread, and special care must be taken in all OpenXRExtensionWrappers in order to prevent crashes or unexpected behavior. Some virtual methods will be called on the render thread, and any data they access should not be directly written to on the main thread. This is to prevent two potential issues:
Changes intended for the next frame, taking effect on the current frame. When using the "Separate" thread model, the main thread will immediately start working on the next frame while the render thread may still be rendering the current frame. If the main thread changes anything used by the render thread directly, the change could end up being used one frame earlier than intended.
Reading and writing to the same data at the same time from different threads can lead to the render thread using data in an invalid state.
In most cases, the solution is to use RenderingServer.call_on_render_thread() to schedule Callables to write to any data used on the render thread. When using the "Separate" thread model, these Callables will run after the renderer finishes the current frame and before it starts rendering the next frame. When not using this mode, they'll run immediately, so it's recommended to always use RenderingServer.call_on_render_thread() in these cases, which will allow your code to do the right thing regardless of the thread model.
Any virtual methods that run on the render thread will be noted below.
Metodi
Descrizioni dei metodi
int _get_composition_layer(index: int) virtual 🔗
Restituisce un puntatore a una struct XrCompositionLayerBaseHeader per fornire il livello di composizione specificato.
Sarà chiamato solo se l'estensione si è precedentemente registrata con OpenXRAPIExtension.register_composition_layer_provider().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering. Inoltre, i dati restituiti saranno utilizzati poco dopo la chiamata di questo metodo, quindi devono rimanere validi fino alla prossima volta che _on_pre_render() viene eseguito.
int _get_composition_layer_count() virtual 🔗
Restituisce il numero di livelli di composizione forniti da questo wrapper d'estensione tramite _get_composition_layer().
Sarà chiamato solo se l'estensione si è precedentemente registrata con OpenXRAPIExtension.register_composition_layer_provider().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering. Inoltre, i dati restituiti saranno utilizzati poco dopo la chiamata di questo metodo, quindi devono rimanere validi fino alla prossima volta che _on_pre_render() viene eseguito.
int _get_composition_layer_order(index: int) virtual 🔗
Restituisce un intero che sarà utilizzato per ordinare il livello di composizione fornito tramite _get_composition_layer(). I numeri più bassi sposteranno il livello in cima alla lista, mentre i numeri più alti alla fine. Il livello di proiezione predefinito ha un ordine di 0, quindi i livelli forniti da questo metodo dovrebbero probabilmente essere sopra o sotto (ma non esattamente) 0.
Sarà chiamato solo se l'estensione si è precedentemente registrata con OpenXRAPIExtension.register_composition_layer_provider().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering. Inoltre, i dati restituiti saranno utilizzati poco dopo la chiamata di questo metodo, quindi devono rimanere validi fino alla prossima volta che _on_pre_render() viene eseguito.
Dictionary _get_requested_extensions(xr_version: int) virtual 🔗
Returns a Dictionary of OpenXR extensions related to this extension. xr_version specifies the OpenXR version we're instantiating. This will be zero if the editor requests this list to flag supported features. The Dictionary should contain the name of the extension, mapped to a bool * cast to an integer:
If the
bool *is anullptrthis extension is mandatory.If the
bool *points to a boolean, the boolean will be updated totrueif the extension is enabled.
PackedStringArray _get_suggested_tracker_names() virtual 🔗
Restituisce un PackedStringArray di nomi di tracciatori posizionali utilizzati all'interno del wrapper d'estensione.
Array[Dictionary] _get_viewport_composition_layer_extension_properties() virtual 🔗
Ottiene un array di Dictionary che rappresentano proprietà, proprio come Object._get_property_list(), che saranno aggiunte ai nodi OpenXRCompositionLayer.
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering.
Dictionary _get_viewport_composition_layer_extension_property_defaults() virtual 🔗
Ottiene un Dictionary contenente i valori predefiniti per le proprietà restituite da _get_viewport_composition_layer_extension_properties().
void _on_before_instance_created() virtual 🔗
Called before the OpenXR instance is created.
Note: This virtual method will be called on the main thread, however, it will be called before OpenXR becomes involved in rendering, so it is safe to write to data that will be used by the render thread.
bool _on_event_polled(event: const void*) virtual 🔗
Chiamato quando c'è un evento OpenXR da elaborare. Se implementato, restituisci true se l'evento è stato gestito, altrimenti restituisci false.
void _on_instance_created(instance: int) virtual 🔗
Called right after the OpenXR instance is created.
Note: This virtual method will be called on the main thread, however, it will be called before OpenXR becomes involved in rendering, so it is safe to write to data that will be used by the render thread.
void _on_instance_destroyed() virtual 🔗
Called right before the OpenXR instance is destroyed.
Note: This virtual method will be called on the main thread, however, it will be called after OpenXR is done being involved in rendering, so it is safe to write to data that was used by the render thread.
void _on_main_swapchains_created() virtual 🔗
Called right after the main swapchains are (re)created.
Note: This virtual method will be called on the render thread.
void _on_post_draw_viewport(viewport: RID) virtual 🔗
Chiamato subito dopo il rendering della viewport specificata.
Nota: I comandi di disegno potrebbero essere solo in coda a questo punto, non eseguiti.
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering.
void _on_pre_draw_viewport(viewport: RID) virtual 🔗
Called right before the given viewport is rendered.
Note: This virtual method will be called on the render thread.
void _on_pre_render() virtual 🔗
Chiamato subito prima che le viewport XR inizino la fase di rendering.
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering.
void _on_process() virtual 🔗
Chiamato come parte della gestione del processo OpenXR. Questo avviene subito prima delle fasi di elaborazione generale e della fisica del ciclo principale. Durante questa fase i dati del controller sono interrogati e resi disponibili alla logica del gioco.
void _on_register_metadata(interaction_profile_metadata: OpenXRInteractionProfileMetadata) virtual 🔗
Consente alle estensioni di registrare metadati aggiuntivi per i controller. Questa funzione viene chiamata anche quando l'API OpenXR non è costruita, poiché i metadati devono essere disponibili all'editor.
Le estensioni devono anche fornire metadati a prescindere dal fatto che siano supportate o meno sul sistema host. I dati dei controller sono utilizzati per configurare le mappe di azioni per gli utenti che potrebbero avere accesso all'hardware pertinente.
void _on_session_created(session: int) virtual 🔗
Called right after the OpenXR session is created.
Note: This virtual method will be called on the main thread, however, it will be called before OpenXR becomes involved in rendering, so it is safe to write to data that will be used by the render thread.
void _on_session_destroyed() virtual 🔗
Called right before the OpenXR session is destroyed.
Note: This virtual method will be called on the main thread, however, it will be called after OpenXR is done being involved in rendering, so it is safe to write to data that was used by the render thread.
void _on_state_exiting() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in uscita.
void _on_state_focused() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in focalizzato. Questo stato è lo stato attivo quando il gioco è in esecuzione.
void _on_state_idle() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in inattivo.
void _on_state_loss_pending() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in perdita in sospeso.
void _on_state_ready() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in pronto. Ciò significa che OpenXR è pronto a configurare la sessione.
void _on_state_stopping() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in arresto.
void _on_state_synchronized() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in sincronizzato. OpenXR torna a questo stato anche quando l'applicazione perde il focus.
void _on_state_visible() virtual 🔗
Chiamato quando lo stato della sessione OpenXR viene cambiato in visibile. Ciò significa che OpenXR è ora pronto a ricevere i frame.
void _on_sync_actions() virtual 🔗
Chiamato quando OpenXR ha effettuato la sua sincronizzazione di azioni.
void _on_viewport_composition_layer_destroyed(layer: const void*) virtual 🔗
Chiamato quando un livello di composizione creato tramite OpenXRCompositionLayer viene distrutto.
layer è un puntatore a una struct XrCompositionLayerBaseHeader.
void _prepare_view_configuration(view_count: int) virtual 🔗
Called before _set_view_configuration_and_get_next_pointer() to allow the extension to reserve data for the given number of views.
void _print_view_configuration_info(view: int) virtual const 🔗
Called to allow an extension to print additional information about its view configuration, if applicable. This will only be called if verbose output is enabled.
int _set_android_surface_swapchain_create_info_and_get_next_pointer(property_values: Dictionary, next_pointer: void*) virtual 🔗
Aggiunge ulteriori strutture dati alle swapchain di superfice di Android create da OpenXRCompositionLayer.
property_values contiene i valori delle proprietà restituite da _get_viewport_composition_layer_extension_properties().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering.
int _set_frame_end_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
Aggiunge ulteriori strutture dati a XrFrameEndInfo.
Sarà chiamato solo se l'estensione si è precedentemente registrata con OpenXRAPIExtension.register_frame_info_extension().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering. Inoltre, i dati restituiti saranno utilizzati poco dopo la chiamata di questo metodo, quindi devono rimanere validi fino alla prossima volta che _on_pre_render() viene eseguito.
int _set_frame_wait_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
Aggiunge ulteriori strutture dati a XrFrameWaitInfo.
Sarà chiamato solo se l'estensione si è precedentemente registrata con OpenXRAPIExtension.register_frame_info_extension().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering.
int _set_hand_joint_locations_and_get_next_pointer(hand_index: int, next_pointer: void*) virtual 🔗
Add additional data structures when each hand tracker is created.
int _set_instance_create_info_and_get_next_pointer(xr_version: int, next_pointer: void*) virtual 🔗
Add additional data structures when the OpenXR instance is created. xr_version specifies the OpenXR version we're instantiating.
int _set_projection_layer_and_get_next_pointer(next_pointer: void*) virtual 🔗
Adds additional data structures to XrCompositionLayerProjection.
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_projection_layer_extension().
int _set_projection_views_and_get_next_pointer(view_index: int, next_pointer: void*) virtual 🔗
Add additional data structures to the projection view of the given view_index.
Note: This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time _on_pre_render() runs.
int _set_reference_space_create_info_and_get_next_pointer(reference_space_type: int, next_pointer: void*) virtual 🔗
Add additional data structures to XrReferenceSpaceCreateInfo.
int _set_session_create_and_get_next_pointer(next_pointer: void*) virtual 🔗
Add additional data structures when the OpenXR session is created.
int _set_swapchain_create_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
Add additional data structures when creating OpenXR swapchains.
int _set_system_properties_and_get_next_pointer(next_pointer: void*) virtual 🔗
Add additional data structures when querying OpenXR system abilities.
int _set_view_configuration_and_get_next_pointer(view: int, next_pointer: void*) virtual 🔗
Add additional data structures when querying OpenXR view configuration.
int _set_view_locate_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
Aggiunge ulteriori strutture dati a XrViewLocateInfo.
Sarà chiamato solo se l'estensione si è precedentemente registrata con OpenXRAPIExtension.register_frame_info_extension().
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering. Inoltre, i dati restituiti saranno utilizzati poco dopo la chiamata di questo metodo, quindi devono rimanere validi fino alla prossima volta che _on_pre_render() viene eseguito.
int _set_viewport_composition_layer_and_get_next_pointer(layer: const void*, property_values: Dictionary, next_pointer: void*) virtual 🔗
Aggiunge ulteriori strutture dati ai livelli di composizione creati da OpenXRCompositionLayer.
property_values contiene i valori delle proprietà restituite da _get_viewport_composition_layer_extension_properties().
layer è un puntatore a una struct XrCompositionLayerBaseHeader.
Nota: Questo metodo virtuale sarà chiamato sul thread di rendering. Inoltre, i dati restituiti saranno utilizzati poco dopo la chiamata di questo metodo, quindi devono rimanere validi fino alla prossima volta che _on_pre_render() viene eseguito.
OpenXRAPIExtension get_openxr_api() 🔗
Restituisce l'estensione OpenXRAPIExtension creata, che può essere utilizzata per accedere all'API dell'OpenXR.
void register_extension_wrapper() 🔗
Registra l'estensione. Ciò dovrebbe avvenire a livello di inizializzazione principale dei moduli.
Nota: Non è possibile chiamare questo metodo una volta che OpenXR è stato inizializzato.