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
继承： Object
派生： OpenXRAndroidThreadSettingsExtension, OpenXRExtensionWrapperExtension, OpenXRFrameSynthesisExtension, OpenXRFutureExtension, OpenXRRenderModelExtension, OpenXRSpatialAnchorCapability, OpenXRSpatialEntityExtension, OpenXRSpatialMarkerTrackingCapability, OpenXRSpatialPlaneTrackingCapability
允许使用 GDExtension 实现 OpenXR 扩展。
描述
OpenXRExtensionWrapper 允许使用 GDExtension 实现 OpenXR 扩展。扩展必须使用 register_extension_wrapper() 方法进行注册。
当 OpenXRInterface 被初始化为主接口，并且任何 Viewport 的 Viewport.use_xr 被设置为 true 时，OpenXR 将参与 Godot 的渲染过程。如果 ProjectSettings.rendering/driver/threads/thread_model 被设置为“Separate”，Godot 的渲染器将在其自己的线程上运行，因此所有 OpenXRExtensionWrapper 都必须特别注意，以防止崩溃或意外行为。一些虚方法将在渲染线程上调用，它们访问的任何数据都不应在主线程上直接写入。这是为了防止两个潜在问题：
旨在用于下一帧的更改，却在当前帧生效。使用“Separate”线程模型时，主线程会立即开始处理下一帧，而渲染线程可能仍在渲染当前帧。如果主线程直接更改渲染线程使用的任何内容，则更改可能会比预期提前一帧生效。
从不同的线程同时读取和写入相同的数据会导致渲染线程使用处于无效状态的数据。
在大多数情况下，解决方案是使用 RenderingServer.call_on_render_thread() 来调度 Callable 函数，以便写入渲染线程上使用的任何数据。使用“Separate”线程模型时，这些 Callable 函数将在渲染器完成当前帧渲染后、开始渲染下一帧之前运行。不使用该模式时，它们会立即运行，因此建议始终在这些情况下使用 RenderingServer.call_on_render_thread()，这样无论使用哪种线程模型，你的代码都能正常工作。
任何在渲染线程上运行的虚方法都将在下面注明。
方法
方法说明
int _get_composition_layer(index: int) virtual 🔗
返回指向 XrCompositionLayerBaseHeader 结构的指针以提供给定的合成层。
仅当扩展先前使用 OpenXRAPIExtension.register_composition_layer_provider() 注册自身后才会调用该函数。
注意：该虚方法将在渲染线程上调用。此外，它返回的数据将在调用该方法后不久使用，因此它需要保持有效，直到下次 _on_pre_render() 运行为止。
int _get_composition_layer_count() virtual 🔗
通过 _get_composition_layer() 返回该扩展包装器提供的合成层数量。
仅当扩展先前使用 OpenXRAPIExtension.register_composition_layer_provider() 注册自身时，才会调用该方法。
注意：该虚方法将在渲染线程上调用。此外，它返回的数据将在调用该方法后不久使用，因此它需要保持有效，直到下次 _on_pre_render() 运行为止。
int _get_composition_layer_order(index: int) virtual 🔗
返回一个整数，该整数将用于对通过 _get_composition_layer() 提供的给定合成层进行排序。数字越小，层就越容易移到列表的最前面，数字越大，层就越容易移到列表的最后面。默认投影层的顺序为 0，因此该方法提供的层可能应该位于（但不完全位于）0 的上方或下方。
仅当扩展程序先前使用 OpenXRAPIExtension.register_composition_layer_provider() 注册自身时，才会调用该方法。
注意：该虚方法将在渲染线程上调用。此外，它返回的数据将在调用该方法后不久使用，因此它需要保持有效，直到下次 _on_pre_render() 运行为止。
Dictionary _get_requested_extensions(xr_version: int) virtual 🔗
返回与该扩展相关的 OpenXR 扩展的 Dictionary。xr_version 指定我们正在实例化的 OpenXR 版本。如果编辑器请求该列表以标记支持的功能，则该值将为零。Dictionary 应包含扩展的名称，并将其映射到一个强制转换为整数的 bool * 类型指针：
如果
bool *是nullptr，则该扩展是强制性的。如果
bool *指向布尔值，则在启用扩展的情况下，该布尔值将更新为true。
PackedStringArray _get_suggested_tracker_names() virtual 🔗
返回扩展包装器中使用的位置跟踪器名称的 PackedStringArray。
Array[Dictionary] _get_viewport_composition_layer_extension_properties() virtual 🔗
获取表示属性的 Dictionary 数组，就像 Object._get_property_list() 一样，将被添加到 OpenXRCompositionLayer 节点。
注意：该虚方法将在渲染线程上调用。
Dictionary _get_viewport_composition_layer_extension_property_defaults() virtual 🔗
获取一个 Dictionary，其中包含 _get_viewport_composition_layer_extension_properties() 返回的属性的默认值。
void _on_before_instance_created() virtual 🔗
在 OpenXR 实例创建之前调用。
注意：该虚方法将在主线程上调用，但它会在 OpenXR 参与渲染之前调用，因此可以安全地写入渲染线程将使用的数据。
bool _on_event_polled(event: const void*) virtual 🔗
当有 OpenXR 事件需要处理时调用。实现时，如果事件已被处理，则返回 true，否则返回 false。
void _on_instance_created(instance: int) virtual 🔗
在 OpenXR 实例创建后立即调用。
注意：该虚方法将在主线程上调用，但会在 OpenXR 参与渲染之前调用，因此可以安全地写入渲染线程将使用的数据。
void _on_instance_destroyed() virtual 🔗
在 OpenXR 实例销毁之前调用。
注意：该虚方法将在主线程上调用，但会在 OpenXR 完成渲染之后调用，因此可以安全地写入渲染线程使用的数据。
void _on_main_swapchains_created() virtual 🔗
在主交换链（重新）创建后立即调用。
注意：该虚方法将在渲染线程上调用。
void _on_post_draw_viewport(viewport: RID) virtual 🔗
在给定视口渲染完成后立即调用。
注意：此时绘制命令可能只是在队列中，尚未执行。
注意：该虚方法将在渲染线程上调用。
void _on_pre_draw_viewport(viewport: RID) virtual 🔗
在给定视口渲染之前调用。
注意：该虚方法将在渲染线程上调用。
void _on_pre_render() virtual 🔗
在 XR 视口开始其渲染步骤之前调用。
注意：该虚方法将在渲染线程上调用。
void _on_process() virtual 🔗
作为 OpenXR 进程处理的一部分调用。这发生在主循环的一般和物理处理步进之前。在该步进中，控制器数据被查询并可供游戏逻辑使用。
void _on_register_metadata(interaction_profile_metadata: OpenXRInteractionProfileMetadata) virtual 🔗
允许扩展注册额外的控制器元数据。即使 OpenXR API 未被构造，也会调用该函数，因为元数据需要可供编辑器使用。
扩展还应该提供元数据，无论主机系统是否支持它们。控制器数据用于为可以访问相关硬件的用户设置动作映射。
void _on_session_created(session: int) virtual 🔗
在 OpenXR 会话创建后立即调用。
注意：该虚方法将在主线程上调用，但会在 OpenXR 参与渲染之前调用，因此可以安全地写入渲染线程将使用的数据。
void _on_session_destroyed() virtual 🔗
在 OpenXR 会话销毁之前调用。
注意：该虚方法将在主线程上调用，但会在 OpenXR 完成渲染相关操作之后调用，因此可以安全地写入渲染线程使用的数据。
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 🔗
在 _set_view_configuration_and_get_next_pointer() 之前调用，以允许扩展为给定数量的视图保留数据。
void _print_view_configuration_info(view: int) virtual const 🔗
如果适用，调用以用于允许扩展打印有关其视图配置的更多信息。仅当详细输出启用时才会调用该方法。
int _set_android_surface_swapchain_create_info_and_get_next_pointer(property_values: Dictionary, next_pointer: void*) virtual 🔗
向由 OpenXRCompositionLayer 创建的 Android 表面交换链添加额外的数据结构。
property_values 包含 _get_viewport_composition_layer_extension_properties() 返回的属性值。
注意：该虚方法将在渲染线程上调用。
int _set_frame_end_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
向 XrFrameEndInfo 添加额外的数据结构。
仅当扩展之前已通过 OpenXRAPIExtension.register_frame_info_extension() 注册自身后才会调用。
注意：该虚方法将在渲染线程上调用。此外，它返回的数据将在调用该方法后不久使用，因此该数据必须保持有效，直到下次 _on_pre_render() 运行。
int _set_frame_wait_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
向 XrFrameWaitInfo 添加额外的数据结构。
仅当扩展之前已通过 OpenXRAPIExtension.register_frame_info_extension() 方法注册自身后才会调用。
注意：该虚方法将在渲染线程上调用。
int _set_hand_joint_locations_and_get_next_pointer(hand_index: int, next_pointer: void*) virtual 🔗
当每个手部跟踪器被创建时添加额外的数据结构。
int _set_instance_create_info_and_get_next_pointer(xr_version: int, next_pointer: void*) virtual 🔗
在 OpenXR 实例被创建时添加额外的数据结构。xr_version 指定我们要实例化的 OpenXR 版本。
int _set_projection_layer_and_get_next_pointer(next_pointer: void*) virtual 🔗
向 XrCompositionLayerProjection 添加额外的数据结构。
仅当该扩展此前已通过 OpenXRAPIExtension.register_projection_layer_extension() 完成注册时，才会调用此方法。
int _set_projection_views_and_get_next_pointer(view_index: int, next_pointer: void*) virtual 🔗
向给定 view_index 的投影视图添加额外数据结构。
注意：该虚方法将在渲染线程上调用。此外，该方法返回的数据将在调用该方法后不久使用，因此它需要保持有效，直到下次 _on_pre_render() 运行。
int _set_reference_space_create_info_and_get_next_pointer(reference_space_type: int, next_pointer: void*) virtual 🔗
向 XrReferenceSpaceCreateInfo 添加额外的数据结构。
int _set_session_create_and_get_next_pointer(next_pointer: void*) virtual 🔗
在 OpenXR 会话创建时添加额外的数据结构。
int _set_swapchain_create_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
在 OpenXR 交换链创建时添加额外的数据结构。
int _set_system_properties_and_get_next_pointer(next_pointer: void*) virtual 🔗
在查询 OpenXR 系统功能时添加额外的数据结构。
int _set_view_configuration_and_get_next_pointer(view: int, next_pointer: void*) virtual 🔗
在查询 OpenXR 视图配置时添加额外的数据结构。
int _set_view_locate_info_and_get_next_pointer(next_pointer: void*) virtual 🔗
为 XrViewLocateInfo 添加额外的数据结构。
仅当扩展先前使用 OpenXRAPIExtension.register_frame_info_extension() 注册自身时才会调用该函数。
注意：该虚方法将在渲染线程上调用。此外，该方法返回的数据将在调用该方法后不久使用，因此它需要保持有效，直到下次 _on_pre_render() 运行。
int _set_viewport_composition_layer_and_get_next_pointer(layer: const void*, property_values: Dictionary, next_pointer: void*) virtual 🔗
向由 OpenXRCompositionLayer 创建的合成层添加其他数据结构。
property_values 包含 _get_viewport_composition_layer_extension_properties() 返回的属性值。
layer 是指向 XrCompositionLayerBaseHeader 结构的指针。
注意：该虚方法将在渲染线程上调用。此外，该方法返回的数据将在调用该方法后不久使用，因此它需要保持有效，直到下次 _on_pre_render() 运行。
OpenXRAPIExtension get_openxr_api() 🔗
返回创建的 OpenXRAPIExtension，可用于访问 OpenXR API。
void register_extension_wrapper() 🔗
注册扩展。这应该发生在核心模块初始化阶段。
注意：OpenXR 初始化后不能再调用该函数。