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

OpenXRSpatialEntityExtension

实验性： This class may be changed or removed in future versions.

继承： OpenXRExtensionWrapper < Object

用于处理空间实体的 OpenXR 扩展。

描述

OpenXR 扩展，用于处理空间实体，启用后允许查询这些空间实体。该扩展还将自动管理静态实体的 XRTracker 对象。

方法

RID	add_spatial_entity(spatial_context: RID, entity_id: int, entity: int)
OpenXRFutureResult	create_spatial_context(capability_configurations: Array[OpenXRSpatialCapabilityConfigurationBaseHeader], next: OpenXRStructureBase = null, user_callback: Callable = Callable())
OpenXRFutureResult	discover_spatial_entities(spatial_context: RID, component_types: PackedInt64Array, next: OpenXRStructureBase = null, user_callback: Callable = Callable())
OpenXRFutureResult	discover_spatial_entities_with_component_data(spatial_context: RID, component_data: Array[OpenXRSpatialComponentData], next: OpenXRStructureBase = null, user_callback: Callable = Callable())
RID	find_spatial_entity(entity_id: int)
void	free_spatial_context(spatial_context: RID)
void	free_spatial_entity(entity: RID)
void	free_spatial_snapshot(spatial_snapshot: RID)
PackedFloat32Array	get_float_buffer(spatial_snapshot: RID, buffer_id: int) const
int	get_spatial_context_handle(spatial_context: RID) const
bool	get_spatial_context_ready(spatial_context: RID) const
RID	get_spatial_entity_context(entity: RID) const
int	get_spatial_entity_id(entity: RID) const
RID	get_spatial_snapshot_context(spatial_snapshot: RID) const
int	get_spatial_snapshot_handle(spatial_snapshot: RID) const
String	get_string(spatial_snapshot: RID, buffer_id: int) const
PackedByteArray	get_uint8_buffer(spatial_snapshot: RID, buffer_id: int) const
PackedInt32Array	get_uint16_buffer(spatial_snapshot: RID, buffer_id: int) const
PackedInt32Array	get_uint32_buffer(spatial_snapshot: RID, buffer_id: int) const
PackedVector2Array	get_vector2_buffer(spatial_snapshot: RID, buffer_id: int) const
PackedVector3Array	get_vector3_buffer(spatial_snapshot: RID, buffer_id: int) const
RID	make_spatial_entity(spatial_context: RID, entity_id: int)
bool	query_snapshot(spatial_snapshot: RID, component_data: Array[OpenXRSpatialComponentData], next: OpenXRStructureBase = null)
bool	supports_capability(capability: Capability)
bool	supports_component_type(capability: Capability, component_type: ComponentType)
RID	update_spatial_entities(spatial_context: RID, entities: Array[RID], component_types: PackedInt64Array, next: OpenXRStructureBase = null)

信号

spatial_discovery_recommended(spatial_context: RID) 🔗

当 OpenXR 建议运行发现查询时发出该信号，因为该空间上下文管理的实体（可能）已发生更改。

枚举

enum Capability: 🔗

Capability CAPABILITY_PLANE_TRACKING = 1000741000

平面跟踪功能。

Capability CAPABILITY_MARKER_TRACKING_QR_CODE = 1000743000

基于二维码的标记跟踪功能。

Capability CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE = 1000743001

基于微型二维码的标记跟踪功能。

Capability CAPABILITY_MARKER_TRACKING_ARUCO_MARKER = 1000743002

基于 Aruco 标记的标记跟踪功能。

Capability CAPABILITY_MARKER_TRACKING_APRIL_TAG = 1000743003

基于 April 标签的标记跟踪功能。

Capability CAPABILITY_ANCHOR = 1000762000

锚点功能。

enum ComponentType: 🔗

ComponentType COMPONENT_TYPE_BOUNDED_2D = 1

为空间实体提供 2D 边界的组件。相应的列表结构为 XrSpatialComponentBounded2DListEXT；相应的数据结构为 XrSpatialBounded2DDataEXT。

ComponentType COMPONENT_TYPE_BOUNDED_3D = 2

为空间实体提供 3D 边界的组件。相应的列表结构为 XrSpatialComponentBounded3DListEXT；相应的数据结构为 XrBoxf。

ComponentType COMPONENT_TYPE_PARENT = 3

为空间实体提供父级 XrSpatialEntityIdEXT 的组件。相应的列表结构为 XrSpatialComponentParentListEXT；相应的数据结构为 XrSpatialEntityIdEXT。

ComponentType COMPONENT_TYPE_MESH_3D = 4

为空间实体提供 3D 网格的组件。相应的列表结构为 XrSpatialComponentMesh3DListEXT；相应的数据结构为 XrSpatialMeshDataEXT。

ComponentType COMPONENT_TYPE_PLANE_ALIGNMENT = 1000741000

为空间实体提供平面对齐枚举的组件。相应的列表结构为 XrSpatialComponentPlaneAlignmentListEXT；相应的数据结构为 XrSpatialPlaneAlignmentEXT（由 XR_EXT_spatial_plane_tracking 扩展添加）。

ComponentType COMPONENT_TYPE_MESH_2D = 1000741001

为空间实体提供 2D 网格的组件。相应的列表结构为 XrSpatialComponentMesh2DListEXT；相应的数据结构为 XrSpatialMeshDataEXT（由 XR_EXT_spatial_plane_tracking 扩展添加）。

ComponentType COMPONENT_TYPE_POLYGON_2D = 1000741002

为空间实体提供 2D 边界多边形的组件。相应的列表结构为 XrSpatialComponentPolygon2DListEXT；相应的数据结构为 XrSpatialPolygon2DDataEXT（由 XR_EXT_spatial_plane_tracking 扩展添加）。

ComponentType COMPONENT_TYPE_PLANE_SEMANTIC_LABEL = 1000741003

为屏幕提供语义标签的组件。相应的列表结构为 XrSpatialComponentPlaneSemanticLabelListEXT；相应的数据结构为 XrSpatialPlaneSemanticLabelEXT（由 XR_EXT_spatial_plane_tracking 扩展添加）。

ComponentType COMPONENT_TYPE_MARKER = 1000743000

描述标记类型、ID 和位置的组件。相应的列表结构为 XrSpatialComponentMarkerListEXT；相应的数据结构为 XrSpatialMarkerDataEXT（由 XR_EXT_spatial_marker_tracking 扩展添加）。

ComponentType COMPONENT_TYPE_ANCHOR = 1000762000

用于提供锚点位置的组件。相应的列表结构为 XrSpatialComponentAnchorListEXT；相应的数据结构为 XrPosef（由 XR_EXT_spatial_anchor 扩展添加）。

ComponentType COMPONENT_TYPE_PERSISTENCE = 1000763000

该组件用于为空间实体提供持久化的 UUID（通用唯一识别码）。其对应的列表结构是 XrSpatialComponentPersistenceListEXT，对应的数据结构是 XrSpatialPersistenceDataEXT（由 XR_EXT_spatial_persistence 扩展添加）。

方法说明

RID add_spatial_entity(spatial_context: RID, entity_id: int, entity: int) 🔗

注册一个直接在 OpenXR 运行时上创建的实体。

OpenXRFutureResult create_spatial_context(capability_configurations: Array[OpenXRSpatialCapabilityConfigurationBaseHeader], next: OpenXRStructureBase = null, user_callback: Callable = Callable()) 🔗

创建一个新的空间上下文，用于处理所提供的功能配置的实体。capability_configurations 是一个包含所需功能配置数据的 OpenXRSpatialCapabilityConfigurationBaseHeader 数组。

next 是一个可选参数，可以包含用于创建空间上下文的附加信息。

注意：这是一个异步方法，返回一个 OpenXRFutureResult 对象，用于跟踪状态；丢弃该对象不会取消创建过程。如果指定了 user_callback，则成功时会调用该回调函数。该函数的结果数据是空间上下文的 RID。

OpenXRFutureResult discover_spatial_entities(spatial_context: RID, component_types: PackedInt64Array, next: OpenXRStructureBase = null, user_callback: Callable = Callable()) 🔗

启动一个新的发现查询，这将收集由 spatial_context 跟踪的所有对象，这些对象至少具有 component_types 中指定的一种组件类型。

next 是一个可选参数，可以包含用于执行发现查询的附加信息。

注意：这是一个异步方法，它返回一个 OpenXRFutureResult 对象，用于跟踪状态；丢弃该对象不会取消发现过程。如果指定了 user_callback，则成功时会调用该回调函数。该函数的结果数据是快照的 RID。

OpenXRFutureResult discover_spatial_entities_with_component_data(spatial_context: RID, component_data: Array[OpenXRSpatialComponentData], next: OpenXRStructureBase = null, user_callback: Callable = Callable()) 🔗

当调用方仅拥有一个 OpenXRSpatialComponentData Array 且需要发现空间实体时，使用的便捷方法。

RID find_spatial_entity(entity_id: int) 🔗

返回指定空间实体 ID 对应的 RID。

void free_spatial_context(spatial_context: RID) 🔗

释放之前调用 create_spatial_context() 创建的空间上下文。如果空间上下文创建过程仍在进行中，则会取消该异步进程。

void free_spatial_entity(entity: RID) 🔗

释放之前调用 add_spatial_entity() 或 make_spatial_entity() 创建的实体。

void free_spatial_snapshot(spatial_snapshot: RID) 🔗

释放之前调用 discover_spatial_entities() 创建的空间快照。如果空间快照创建仍在进行中，则会取消该异步进程。

PackedFloat32Array get_float_buffer(spatial_snapshot: RID, buffer_id: int) const 🔗

返回一个包含浮点数的缓冲区，该缓冲区是从拍摄快照时获取的缓冲区中提取的。

int get_spatial_context_handle(spatial_context: RID) const 🔗

返回该快照的 OpenXR 空间上下文句柄。

注意：该方法旨在供实现空间实体功能处理程序的 GDExtensions 使用。

bool get_spatial_context_ready(spatial_context: RID) const 🔗

如果空间上下文已完成创建并准备使用，则返回 true。

RID get_spatial_entity_context(entity: RID) const 🔗

返回该实体的空间上下文。

int get_spatial_entity_id(entity: RID) const 🔗

返回与该实体关联的内部 XrSpatialEntityIdEXT。

RID get_spatial_snapshot_context(spatial_snapshot: RID) const 🔗

返回与该空间快照相关的空间上下文。

int get_spatial_snapshot_handle(spatial_snapshot: RID) const 🔗

返回该快照的 OpenXR 空间快照句柄。

注意：该方法旨在供实现空间实体功能处理程序的 GDExtension 扩展使用。

String get_string(spatial_snapshot: RID, buffer_id: int) const 🔗

返回从拍摄快照时获取的缓冲区中提取的字符串。

PackedByteArray get_uint8_buffer(spatial_snapshot: RID, buffer_id: int) const 🔗

从拍摄快照时获取的缓冲区中返回一个包含 8 位整数的缓冲区。

PackedInt32Array get_uint16_buffer(spatial_snapshot: RID, buffer_id: int) const 🔗

从拍摄快照时获取的缓冲区中返回一个包含 16 位整数的缓冲区。

PackedInt32Array get_uint32_buffer(spatial_snapshot: RID, buffer_id: int) const 🔗

从拍摄快照时获取的缓冲区中返回一个包含 32 位整数的缓冲区。

PackedVector2Array get_vector2_buffer(spatial_snapshot: RID, buffer_id: int) const 🔗

从拍摄快照时获取的缓冲区中返回一个包含提取的 Vector2 条目的缓冲区。

PackedVector3Array get_vector3_buffer(spatial_snapshot: RID, buffer_id: int) const 🔗

从拍摄快照时获取的缓冲区中返回一个包含提取的 Vector3 条目的缓冲区。

RID make_spatial_entity(spatial_context: RID, entity_id: int) 🔗

为该 entity_id 创建一个新的实体。spatial_context 应与发现该实体的上下文相匹配。

bool query_snapshot(spatial_snapshot: RID, component_data: Array[OpenXRSpatialComponentData], next: OpenXRStructureBase = null) 🔗

查询快照数据。该函数将查找快照中包含 component_data 中所有指定组件的所有实体。然后，component_data 中包含的对象将填充查询到的数据。component_data 必须始终以 OpenXRSpatialQueryResultData 对象作为第一个条目。

next 是一个可选参数，可包含设置查询条件时传递的附加信息。

bool supports_capability(capability: Capability) 🔗

如果所使用的硬件支持该空间实体 capability，则返回 true。

bool supports_component_type(capability: Capability, component_type: ComponentType) 🔗

如果该 capability 支持 component_type，则返回 true。

RID update_spatial_entities(spatial_context: RID, entities: Array[RID], component_types: PackedInt64Array, next: OpenXRStructureBase = null) 🔗

对有限数量的实体执行快照操作。这不是异步方法，会立即返回快照结果。