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...

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。