OpenXRExtensionWrapper
继承： Object
派生： OpenXRAndroidThreadSettingsExtension, OpenXRExtensionWrapperExtension, OpenXRFrameSynthesisExtension, OpenXRFutureExtension, OpenXRRenderModelExtension, OpenXRSpatialAnchorCapability, OpenXRSpatialEntityExtension, OpenXRSpatialMarkerTrackingCapability, OpenXRSpatialPlaneTrackingCapability
允许使用 GDExtension 实现 OpenXR 扩展。
描述
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.
方法
方法说明
int _get_composition_layer(index: int) virtual 🔗
Returns a pointer to an XrCompositionLayerBaseHeader struct to provide the given composition layer.
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_composition_layer_provider().
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 _get_composition_layer_count() virtual 🔗
Returns the number of composition layers this extension wrapper provides via _get_composition_layer().
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_composition_layer_provider().
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 _get_composition_layer_order(index: int) virtual 🔗
Returns an integer that will be used to sort the given composition layer provided via _get_composition_layer(). Lower numbers will move the layer to the front of the list, and higher numbers to the end. The default projection layer has an order of 0, so layers provided by this method should probably be above or below (but not exactly) 0.
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_composition_layer_provider().
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.
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 🔗
返回扩展包装器中使用的位置跟踪器名称的 PackedStringArray。
Array[Dictionary] _get_viewport_composition_layer_extension_properties() virtual 🔗
Gets an array of Dictionarys that represent properties, just like Object._get_property_list(), that will be added to OpenXRCompositionLayer nodes.
Note: This virtual method will be called on the render thread.
Dictionary _get_viewport_composition_layer_extension_property_defaults() virtual 🔗
获取一个 Dictionary，其中包含 _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 🔗
当有 OpenXR 事件需要处理时调用。实现时，如果事件已被处理，则返回 true，否则返回 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 🔗
Called right after the given viewport is rendered.
Note: The draw commands might only be queued at this point, not executed.
Note: This virtual method will be called on the render thread.
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 🔗
Called right before the XR viewports begin their rendering step.
Note: This virtual method will be called on the render thread.
void _on_process() virtual 🔗
作为 OpenXR 进程处理的一部分调用。这发生在主循环的一般和物理处理步进之前。在该步进中，控制器数据被查询并可供游戏逻辑使用。
void _on_register_metadata() virtual 🔗
允许扩展注册额外的控制器元数据。即使 OpenXR API 未被构造，也会调用该函数，因为元数据需要可供编辑器使用。
扩展还应该提供元数据，无论主机系统是否支持它们。控制器数据用于为可以访问相关硬件的用户设置动作映射。
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 🔗
当 OpenXR 会话状态被更改为退出时调用。
void _on_state_focused() virtual 🔗
当 OpenXR 会话状态被更改为聚焦时调用。该状态是游戏运行时的活动状态。
void _on_state_idle() virtual 🔗
当 OpenXR 会话状态被更改为空闲时调用。
void _on_state_loss_pending() virtual 🔗
当 OpenXR 会话状态被更改为丢失挂起时调用。
void _on_state_ready() virtual 🔗
当 OpenXR 会话状态被更改为就绪时调用。这意味着 OpenXR 已准备好建立会话。
void _on_state_stopping() virtual 🔗
当 OpenXR 会话状态被更改为停止时调用。
void _on_state_synchronized() virtual 🔗
当 OpenXR 会话状态被更改为同步时调用。当应用程序失去焦点时，OpenXR 也会返回到该状态。
void _on_state_visible() virtual 🔗
当 OpenXR 会话状态被更改为可见时调用。这意味着 OpenXR 现在已准备好接收帧。
void _on_sync_actions() virtual 🔗
当 OpenXR 执行完动作同步时调用。
void _on_viewport_composition_layer_destroyed(layer: const void*) virtual 🔗
当通过 OpenXRCompositionLayer 创建的合成层被销毁时调用。
layer 是指向 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 🔗
Add additional data structures to Android surface swapchains created by OpenXRCompositionLayer.
property_values contains the values of the properties returned by _get_viewport_composition_layer_extension_properties().
Note: This virtual method will be called on the render thread.
int _set_frame_end_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
Add additional data structures to XrFrameEndInfo.
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_frame_info_extension().
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_frame_wait_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
Add additional data structures to XrFrameWaitInfo.
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_frame_info_extension().
Note: This virtual method will be called on the render thread.
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_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 🔗
Add additional data structures to XrViewLocateInfo.
This will only be called if the extension previously registered itself with OpenXRAPIExtension.register_frame_info_extension().
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_viewport_composition_layer_and_get_next_pointer(layer: const void*, property_values: Dictionary, next_pointer: void*) virtual 🔗
Add additional data structures to composition layers created by OpenXRCompositionLayer.
property_values contains the values of the properties returned by _get_viewport_composition_layer_extension_properties().
layer is a pointer to an XrCompositionLayerBaseHeader struct.
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.
OpenXRAPIExtension get_openxr_api() 🔗
返回创建的 OpenXRAPIExtension，可用于访问 OpenXR API。
void register_extension_wrapper() 🔗
Registers the extension. This should happen at core module initialization level.
Note: This cannot be called once OpenXR has been initialized.