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, OpenXRSpatialContainerExtension, OpenXRSpatialContainerSelfRenderingExtension, 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(),這樣無論使用哪種執行緒模型,你的程式碼都能正常工作。
任何在渲染執行緒上執行的虛方法都將在下面注明。
方法
方法說明
Array[Transform3D] _get_camera_offsets(tracker_name: StringName) virtual 🔗
Returns an array of offsets for each view rendered for the given camera, if this camera is handled by this extension. tracker_name refers to the camera tracker for which we're retrieving this.
Array[Projection] _get_camera_projections(tracker_name: StringName, aspect: float, z_near: float, z_far: float) virtual 🔗
Returns an array of projections for each view rendered for the given camera, if this camera is handled by this extension. tracker_name refers to the camera tracker for which we're retrieving this.
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 程序處理的一部分呼叫。這發生在主循環的一般和物理處理步驟之前。在此步驟中,控制器資料被查詢並可供遊戲邏輯使用。 “,“,““,“錯誤的”,””,”,””
modules/openxr/doc_classes/OpenXRExtensionWrapperExtension.xml"
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_spatial_container_create_info_and_get_next_pointer(spatial_container: RID, next_pointer: void*) virtual 🔗
Add additional data structures when the spatial container is created.
int _set_spatial_container_views_locate_info_and_get_next_pointer(spatial_container: RID, next_pointer: void*) virtual 🔗
Add additional data structures to XrSpatialContainerViewsLocateInfoEXT for the spatial container specified by spatial_container.
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_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 初始化後不能再呼叫該函式。