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.

OpenXRSpatialAnchorCapability

實驗性: This class may be changed or removed in future versions.

繼承: OpenXRExtensionWrapper < Object

用於處理空間實體錨點邏輯的實作。

說明

這是一個內部類,用於處理 OpenXR 錨點空間實體擴充。

方法

OpenXRFutureResult

create_default_persistence_context(user_callback: Callable = Callable())

OpenXRAnchorTracker

create_new_anchor(transform: Transform3D, spatial_context: RID = RID(), next: OpenXRStructureBase = null)

OpenXRFutureResult

create_persistence_context(scope: PersistenceScope, user_callback: Callable = Callable())

void

do_entity_update(spatial_context: RID, component_data: Array[OpenXRSpatialComponentData], next_snapshot_create: OpenXRStructureBase = null, next_snapshot_query: OpenXRStructureBase = null)

void

free_persistence_context(persistence_context: RID)

int

get_persistence_context_handle(persistence_context: RID) const

bool

is_persistence_scope_supported(scope: PersistenceScope)

bool

is_spatial_anchor_supported()

bool

is_spatial_persistence_supported()

OpenXRFutureResult

persist_anchor(anchor_tracker: OpenXRAnchorTracker, persistence_context: RID = RID(), user_callback: Callable = Callable())

void

remove_anchor(anchor_tracker: OpenXRAnchorTracker)

OpenXRFutureResult

start_entity_discovery(spatial_context: RID, component_data: Array[OpenXRSpatialComponentData], next_snapshot_create: OpenXRStructureBase = null, next_snapshot_query: OpenXRStructureBase = null, user_callback: Callable = Callable())

OpenXRFutureResult

unpersist_anchor(anchor_tracker: OpenXRAnchorTracker, persistence_context: RID = RID(), user_callback: Callable = Callable())


列舉

enum PersistenceScope: 🔗

PersistenceScope PERSISTENCE_SCOPE_SYSTEM_MANAGED = 1

為應用程式提供對由系統持久化和管理的空間實體的只讀存取權限(即應用程式不能修改該範圍)。應用程式可以使用該範圍的持久化元件中的 UUID,以便在不同的地理空間情境和裝置重啓後關聯實體。

PersistenceScope PERSISTENCE_SCOPE_LOCAL_ANCHORS = 1000781000

持久化操作和資料存取僅限於同一裝置、同一使用者和同一應用程式的空間錨點(使用 persist_anchor() 和 unpersist_anchor() 函式)


方法說明

OpenXRFutureResult create_default_persistence_context(user_callback: Callable = Callable()) 🔗

使用一種很可能與 XR 執行時相容的設定,呼叫 create_persistence_context() 方法。

當情境建立完成時,將呼叫 user_callback 回呼函式。


OpenXRAnchorTracker create_new_anchor(transform: Transform3D, spatial_context: RID = RID(), next: OpenXRStructureBase = null) 🔗

建立一個新的錨點(anchor),該錨點將由 XR 執行時進行追蹤。transform(變換矩陣)應該是相對於你的 XROrigin3D 節點的區域空間座標。如果未指定 spatial_context(空間情境),將使用預設值,但這要求必須啟用 ProjectSettings.xr/openxr/extensions/spatial_entity/enable_builtin_anchor_detection 選項。回傳的追蹤器(tracker)會在我們的參考空間發生變化時,持續追蹤該錨點的位置。

next 必須是一個有效的物件,用於 XrSpatialAnchorCreateInfoEXT 擴充鏈。


OpenXRFutureResult create_persistence_context(scope: PersistenceScope, user_callback: Callable = Callable()) 🔗

建立一個新的持久化情境,用於儲存持久化資料。

注意:這是一個非同步方法,它回傳一個 OpenXRFutureResult 物件,用於追蹤狀態;丟棄該物件不會取消建立過程。如果指定了 user_callback,則建立成功後會呼叫該回呼函式。該函式的回傳值是持久化情境的 RID。


void do_entity_update(spatial_context: RID, component_data: Array[OpenXRSpatialComponentData], next_snapshot_create: OpenXRStructureBase = null, next_snapshot_query: OpenXRStructureBase = null) 🔗

使用與 spatial_context 關聯的錨點實體,呼叫 OpenXRSpatialEntityExtension.update_spatial_entities() 和 OpenXRSpatialEntityExtension.query_snapshot() 方法。

component_data 是針對此錨點功能需要更新的 OpenXRSpatialComponentData 資料。

如果 next_snapshot_create 不為空,則將其作為 next 參數傳遞給 OpenXRSpatialEntityExtension.update_spatial_entities() 方法;

如果 next_snapshot_query 不為空,則將其作為 next 參數傳遞給 OpenXRSpatialEntityExtension.query_snapshot() 方法。


void free_persistence_context(persistence_context: RID) 🔗

釋放之前使用 create_persistence_context() 建立的持久化情境。


int get_persistence_context_handle(persistence_context: RID) const 🔗

回傳該持久化情境的內部控制代碼。

注意:適用於 GDExtension 實作。


bool is_persistence_scope_supported(scope: PersistenceScope) 🔗

如果空間錨點功能支援該持久性範圍,則回傳 true。

注意:該方法僅在 OpenXR 實例建立後有效。


bool is_spatial_anchor_supported() 🔗

如果硬體支援空間錨點功能,則回傳 true。該函式只有在 OpenXR 初始化後才會回傳有效值。


bool is_spatial_persistence_supported() 🔗

如果硬體支援持久空間錨點,則回傳 true。僅在 OpenXR 初始化後才會回傳有效值。


OpenXRFutureResult persist_anchor(anchor_tracker: OpenXRAnchorTracker, persistence_context: RID = RID(), user_callback: Callable = Callable()) 🔗

將該錨點轉換為持久錨點。這意味著其位置將儲存在裝置上,並在下次應用程式啟動時恢復該錨點。如果未指定 persistence_context,則將使用預設值,但這需要設定 ProjectSettings.xr/openxr/extensions/spatial_entity/enable_builtin_anchor_detection。

注意:這是一個非同步方法,它回傳一個 OpenXRFutureResult 物件,用於追蹤狀態;丟棄該物件不會取消建立過程。如果指定了 user_callback,則在成功完成後將呼叫該回呼函式。該函式的回傳值是一個布林值,成功完成後將被設定為 true。


void remove_anchor(anchor_tracker: OpenXRAnchorTracker) 🔗

移除之前使用 create_new_anchor() 方法建立的錨點。如果該錨點是持久化的,則必須先呼叫 unpersist_anchor() 並等待其回呼完成。


OpenXRFutureResult start_entity_discovery(spatial_context: RID, component_data: Array[OpenXRSpatialComponentData], next_snapshot_create: OpenXRStructureBase = null, next_snapshot_query: OpenXRStructureBase = null, user_callback: Callable = Callable()) 🔗

使用與 spatial_context 關聯的錨點實體,呼叫 OpenXRSpatialEntityExtension.discover_spatial_entities() 和 OpenXRSpatialEntityExtension.query_snapshot() 方法。

component_data 是針對此錨點功能需要發現的 OpenXRSpatialComponentData 資料。

如果 next_snapshot_create 不為空,則將其作為 next 參數傳遞給 OpenXRSpatialEntityExtension.discover_spatial_entities() 方法;

如果 next_snapshot_query 不為空,則將其作為 next 參數傳遞給 OpenXRSpatialEntityExtension.query_snapshot() 方法。

user_callback 在非空時,通常會被呼叫兩次,並傳入兩個參數。第一個參數是發現快照(discovery snapshot)的 RID,第二個參數是一個布林值:false 表示發現快照即將被處理,true 表示發現快照已處理完畢且 component_data 包含有效資料。如果遇到錯誤,則會跳過第二次呼叫。

回傳的 OpenXRFutureResult 與 OpenXRSpatialEntityExtension.discover_spatial_entities() 的回傳值相同。


OpenXRFutureResult unpersist_anchor(anchor_tracker: OpenXRAnchorTracker, persistence_context: RID = RID(), user_callback: Callable = Callable()) 🔗

移除該錨點的持久化資料。應用程式重啓後,執行時將不會重新建立該錨點。如果未指定 persistence_context,則將使用預設值,但這需要啟用 ProjectSettings.xr/openxr/extensions/spatial_entity/enabled。

注意:這是一個非同步方法,它回傳一個 OpenXRFutureResult 物件,用於追蹤狀態;丟棄該物件不會取消建立過程。如果指定了 user_callback,則成功完成後會呼叫該回呼函式。該函式的回傳值為布林值,成功完成後將被設定為 true。