XR_EXT_spatial_entity

名称字符串

XR_EXT_spatial_entity

扩展程序类型

实例扩展程序

已注册的扩展程序编号

741

修订版本

1

批准状态

已批准

扩展程序和版本依赖项

XR_EXT_future

创作贡献者

Nihav Jain，Google
Jared Finder，Google
Natalie Fleury，Meta
Yuichi Taguchi，Meta
Ron Bessems，Meta
Yin Li，Microsoft
Karthik Kadappan，Magic Leap
Jimmy Alamparambil，ByteDance
Zhipeng Liu，ByteDance
Jun Yan，ByteDance

概览

此扩展程序介绍了 OpenXR 中场景理解和空间推理的概念和基础。这统一了几个相关但不同的功能领域，这些功能领域通过此扩展程序定义的方式进行枚举、配置和交互。由于此扩展程序缺少对这些功能区域中任何一个的具体定义，因此正式规范文本往往有些抽象。本扩展规范文本中包含的示例有时会引用即将推出或假设的相关扩展中定义的功能，以便进行说明，但不会固有地限制或指定此类附加功能。

此扩展程序的主要组成部分如下：

  • 空间实体：功能以实体为中心，实体本身提供的功能非常有限。
  • 空间组件：这些实体具有关联的组件，可提供数据和行为。
  • 空间组件类型：每个空间组件都属于特定的组件类型，任何给定的实体最多只有一个属于任何给定组件类型的组件。
  • 空间上下文：所有空间实体交互都会在初始化和配置阶段之后在上下文中发生。
  • 空间功能：空间实体操作主要通过功能提供。功能是指某种功能单元，例如（但不限于）应用定义的锚点、平面检测或图像跟踪。每个功能通常在单独的扩展程序中定义（在实例创建时照常启用），并在创建时为特定上下文启用。
  • 每项功能都与一组组件类型相关联，这些组件类型对应的组件存在于该功能公开的每个实体上。定义功能的扩展程序会指定该功能必须具备哪些组件类型（“保证”），而该扩展程序或其他扩展程序可以指定某些潜在实现提供的可选 组件类型。任意数量的功能都可能为实体提供具有给定组件类型的组件，无论这些组件是由哪种功能生成的，都可以统一使用。
  • 空间功能特性：此外，某些功能需要进行配置，因此通过功能特性进行参数化。

此扩展程序提供了一种机制，用于枚举当前系统支持的每项功能所提供的组件，包括强制性组件和任何可选 组件。

由于某些实现可能需要对功能进行不同程度的参数化，因此该扩展提供了一种机制，用于枚举当前系统中与给定功能关联的受支持功能特性。

此扩展程序还定义了多个通用组件，这些组件预计将在各种功能中使用。

空间实体

空间实体是存在于某个空间中的实体，具有整理成组件的各种关联数据。它们可能是以下任何一种：

  • 物理（例如墙壁和地板等平面、椅子和书柜等物体等）
  • 虚拟（例如，由其他应用或用户放置和分享的内容），
  • 应用定义（例如，应用将某个区域标记为“Living Room”或“厨房”，或将某个点标记为放置电视的位置等）

通过操作系统公开的事物（例如控制器或视线）不应建模为空间实体。

OpenXR 中的空间实体被建模为实体组件系统。每个空间实体都有一组组件，每个组件都为该实体提供一组独特的数据和行为。

空间实体由 XrSpatialEntityIdEXT atom 或 XrSpatialEntityEXT 句柄表示，详情请参阅空间实体表示法部分。

空间组件类型

空间实体具有一个或多个组件，这些组件可为该实体提供数据或行为。如需了解此扩展程序定义的一些常见组件，请参阅常见组件。

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

XrSpatialComponentTypeEXT 枚举用于标识运行时可能支持的不同类型的组件。

并非所有列出的组件类型都由该扩展程序单独提供：有些组件类型需要在创建实例时启用其他扩展程序，如文档中所述。

枚举值具有以下值：

枚举说明

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

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

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

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

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

为平面提供语义标签的组件。对应的列表结构为 XrSpatialComponentPlaneSemanticLabelListEXT；对应的数据结构为 XrSpatialPlaneSemanticLabelEXT（由 XR_EXT_spatial_plane_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

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

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

为场景提供语义标签的组件；对应的列表结构为 XrSpatialComponentObjectSemanticLabelListEXT。对应的数据结构为 XrSpatialObjectSemanticLabelEXT。（由XR_EXT_spatial_object_tracking扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

为键盘提供语义标签的组件；对应的列表结构为 XrSpatialComponentKeyboardSemanticLabelListEXT。对应的数据结构为 XrSpatialKeyboardSemanticLabelEXT（由 XR_EXT_spatial_object_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

为鼠标提供语义标签的组件；对应的列表结构为 XrSpatialComponentMouseSemanticLabelListEXT。相应的数据结构为 XrSpatialMouseSemanticLabelEXT（由 XR_EXT_spatial_object_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

为锚点提供位置信息的组件。对应的列表结构为 XrSpatialComponentAnchorListEXT；对应的数据结构为 XrPosef（由 XR_EXT_spatial_anchor 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

为空间实体提供持久化 UUID 的组件。对应的列表结构为 XrSpatialComponentPersistenceListEXT；对应的数据结构为 XrSpatialPersistenceDataEXT（由 XR_EXT_spatial_persistence 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

描述平面图片类型的组件。对应的列表结构为 XrSpatialComponentImage2DListEXT；对应的数据结构为 XrSpatialImageSizeEXT。（由XR_EXT_spatial_image_tracking扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

为空间实体的 3D 网格提供法线的组件。对应的列表结构为 XrSpatialComponentMesh3DNormalsListEXT；对应的数据结构为 XrSpatialBufferEXT（由 XR_EXT_spatial_mesh_tracking 扩展添加）

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

为空间实体的 3D 网格提供每个顶点的语义标签的组件。对应的列表结构为 XrSpatialComponentMesh3DVertexSemanticLabelsListEXT；对应的数据结构为 XrSpatialBufferEXT；缓冲区内的数据映射到 XrSpatialMeshSemanticLabelEXT（由 XR_EXT_spatial_mesh_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

为空间实体的 3D 网格提供每个三角形面语义标签的组件。对应的列表结构为 XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT；对应的数据结构为 XrSpatialBufferEXT；缓冲区内的数据映射到 XrSpatialMeshSemanticLabelEXT（由 XR_EXT_spatial_mesh_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

为对象提供语义标签的组件；对应的列表结构为 XrSpatialComponentObjectSemanticLabelListANDROID；对应的数据结构为 XrSpatialObjectSemanticLabelANDROID（由 XR_ANDROID_spatial_object_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

提供实体上光线投射命中姿态的组件。对应的列表结构为 XrSpatialComponentRaycastResultListANDROID；对应的数据结构为 XrSpatialRaycastResultDataANDROID（由 XR_ANDROID_spatial_discovery_raycast 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

提供包含所附实体的实体的实体 ID 的组件。对应的列表结构为 XrSpatialComponentSubsumedByListANDROID；对应的数据结构为 XrSpatialEntityIdEXT（由 XR_ANDROID_spatial_component_subsumed_by 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

提供鞋盒尺寸和房间类型的组件；对应的列表结构为 XrSpatialComponentRoomListANDROIDSYS；对应的数据结构为 XrSpatialRoomDataANDROIDSYS（由 XR_ANDROIDSYS_spatial_room_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

提供边界表面材质类型的组件；对应的列表结构为 XrSpatialComponentMaterialTypeListANDROIDSYS；对应的数据结构为 XrSpatialMaterialTypeANDROIDSYS（由 XR_ANDROIDSYS_spatial_room_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

提供可跟踪对象的置信度的组件；对应的列表结构为 XrSpatialComponentConfidenceListANDROIDSYS；对应的数据结构为 float（由 XR_ANDROIDSYS_spatial_room_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

提供房间空置状态的组件；对应的列表结构为 XrSpatialComponentRoomEmptinessListANDROIDSYS；对应的数据结构为 float（由 XR_ANDROIDSYS_spatial_room_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

提供所附实体上占用网格信息的组件。对应的列表结构为 XrSpatialComponentOccupancyGridListANDROIDX1；对应的数据结构为 XrSpatialOccupancyGridDataANDROIDX1（由 XR_ANDROIDX1_spatial_occupancy_grid 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

描述四边形注释的组件。对应的列表结构为 XrSpatialComponentAnnotationQuadListANDROID；对应的数据结构为 XrSpatialAnnotationQuadDataANDROID（由 XR_ANDROID_spatial_annotation_tracking 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

为街景几何图形提供元数据的组件；对应的列表结构为 XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2；对应的数据结构为 XrSpatialStreetscapeGeometryMetadataANDROIDX2（由 XR_ANDROIDX2_geospatial_streetscape 扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

将实体标识为几何图形点的组件。此组件类型没有对应的列表或数据结构。此组件的存在仅表示实体能够附加到锚点。（由XR_ANDROID_spatial_geometry_point扩展程序添加）

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

一个组件，用于描述实体持久化的持久化范围。如果运行时支持 XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT，则必须也支持此组件。相应的数据结构为 XrSpatialBufferEXT。对应的列表结构为 XrSpatialComponentPersistenceScopeDataListANDROIDX1。（由XR_ANDROIDX1_spatial_anchor_cloud_sharing扩展程序添加）

空间功能和设置

空间功能定义了运行时发现具有一组保证组件的实体的能力。应用在创建 XrSpatialContextEXT 时启用空间功能的组件，而运行时必须仅在发现的实体上提供已启用的组件。例如，如果运行时报告给定功能的其中一个组件是“语义标签”，则意味着应用可以通过该功能的配置启用语义标签，并且运行时必须仅在配置了语义标签组件时才提供该组件。

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

XrSpatialCapabilityEXT 枚举用于标识运行时可能支持的不同类型的功能。

枚举值具有以下值：

枚举说明

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

平面跟踪（由 XR_EXT_spatial_plane_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

能够检测和跟踪二维码。（由XR_EXT_spatial_marker_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

能够检测和跟踪微型二维码。（由XR_EXT_spatial_marker_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

能够检测和跟踪 Aruco 标记。（由XR_EXT_spatial_marker_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

能够检测和跟踪 AprilTag。（由XR_EXT_spatial_marker_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

对象跟踪（由 XR_EXT_spatial_object_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

能够创建空间锚点（由 XR_EXT_spatial_anchor 扩展程序添加）

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

能够检测和跟踪平面参考图片。（由XR_EXT_spatial_image_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

能够跟踪环境的网格。（由XR_EXT_spatial_mesh_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

对象跟踪（由 XR_ANDROID_spatial_object_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

针对深度缓冲区进行光线投射（由 XR_ANDROID_spatial_discovery_raycast 扩展程序添加）

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

能够跟踪房间（由 XR_ANDROIDSYS_spatial_room_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

能够跟踪房间边界（由 XR_ANDROIDSYS_spatial_room_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

注释跟踪（由 XR_ANDROID_spatial_annotation_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

街景几何图形（由 XR_ANDROIDX2_geospatial_streetscape 扩展程序添加）

xrEnumerateSpatialCapabilitiesEXT 函数定义如下：

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

参数说明

  • instance 是 XrInstance 的句柄。
  • systemId 是要枚举其空间功能的 XrSystemId。
  • capabilityCapacityInput 是 capabilities 数组的容量，或设为 0 以请求获取所需的容量。
  • capabilityCountOutput 是功能数量；若 capabilityCapacityInput 容量不足，则为所需的容量。
  • capabilities 是一个 XrSpatialCapabilityEXT 数组。如果 capabilityCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 capabilities 大小，请参阅缓冲区大小参数部分。

应用可以使用 xrEnumerateSpatialCapabilitiesEXT 枚举给定 XrSystemId 支持的空间功能列表。

运行时不得枚举未为 instance 启用扩展的空间功能。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能调用 xrEnumerateSpatialCapabilitiesEXT
  • instance 必须是有效的 XrInstance 句柄
  • capabilityCountOutput 必须是指向 uint32_t 值的指针
  • 如果 capabilityCapacityInput 不为 0，则 capabilities 必须是指向 capabilityCapacityInput XrSpatialCapabilityEXT 值数组的指针

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

xrEnumerateSpatialCapabilityComponentTypesEXT 函数定义如下：

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

参数说明

此函数会枚举给定 capability 在系统中的实体上提供的组件类型（按配置）。

应用可以使用 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中枚举的组件类型，了解 systemId 为 capability 支持的完整组件集，并可以使用此列表确定在为 创建 XrSpatialContextEXT 时，capability 的有效配置是什么。

如果 capability 未由 xrEnumerateSpatialCapabilitiesEXT 枚举，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。

运行时不得枚举未为 instance 启用扩展的空间组件类型。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialCapabilityComponentTypesEXT 结构定义如下：

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • componentTypeCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • componentTypeCountOutput 是组件类型的数量；若 componentTypeCapacityInput 容量不足，则为所需的容量。
  • componentTypes 是一个 XrSpatialComponentTypeEXT 数组。如果 componentTypeCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 componentTypes 大小，请参阅缓冲区大小参数部分。

有效用法（隐式）

空间功能

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

某些功能具有向应用公开的参数，用于配置运行时如何计算组件数据。这些参数化/可配置性维度称为功能特性。例如，对于图片跟踪功能，运行时可以支持应用指定跟踪的图片是否静止。

通过配置结构向运行时提供此信息不得更改关联实体（例如跟踪的图片）上存在的组件类型集。不过，运行时可能能够优化图片跟踪功能的跟踪能力等，并为应用提供更好的体验。

此类功能由 XrSpatialCapabilityFeatureEXT 表示，应用使用 xrEnumerateSpatialCapabilityFeaturesEXT 枚举这些功能。

每个功能特性都有一个相应的配置结构来启用它。此类配置结构必须链接到相应功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next。

枚举值具有以下值：

枚举说明

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

功能特性，允许应用指定标记的大小。对应的配置结构为 XrSpatialMarkerSizeEXT（由 XR_EXT_spatial_marker_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

功能特性，允许应用指定标记是否为静态。对应的配置结构为 XrSpatialMarkerStaticOptimizationEXT（由 XR_EXT_spatial_marker_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

空间功能，允许应用从 XrSpatialObjectSemanticLabelEXT 中指定一个标签子集，供运行时跟踪。对应的配置结构为 XrSpatialFeatureObjectSemanticLabelSubsetEXT。（由XR_EXT_spatial_object_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

运行时支持 XrSpatialDiscoverySnapshotCreateInfoEXT 的 XrSpatialBoundsSpherefANDROID 过滤器；这不需要在创建空间上下文期间包含任何配置结构。（由XR_ANDROID_spatial_discovery_bounds扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

运行时支持 XrSpatialDiscoverySnapshotCreateInfoEXT 的 XrSpatialBoundsBoxfANDROID 过滤器；这不需要在创建空间上下文期间包含任何配置结构。（由XR_ANDROID_spatial_discovery_bounds扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

运行时支持 XrSpatialDiscoverySnapshotCreateInfoEXT 的 XrSpatialBoundsFrustumfANDROID 过滤器；这不需要在创建空间上下文期间包含任何配置结构。（由XR_ANDROID_spatial_discovery_bounds扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

运行时支持自动推断检测和跟踪的图片的物理尺寸。对应的配置结构为 XrSpatialImageSizeEXT（由 XR_EXT_spatial_image_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

运行时支持 XrSpatialImageStaticOptimizationEXT。对应的配置结构为 XrSpatialImageStaticOptimizationEXT。（由XR_EXT_spatial_image_tracking扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

运行时支持 XrSpatialImageSizeEXT。对应的配置结构为 XrSpatialImageSizeEXT（由 XR_EXT_spatial_image_tracking 扩展程序添加）

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

用于跟踪环境的水密网格的功能。对应的配置结构为 XrSpatialFeatureTrackWatertightMeshEXT。（由XR_EXT_spatial_mesh_tracking扩展程序添加）

xrEnumerateSpatialCapabilityFeaturesEXT 函数定义如下：

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

参数说明

  • instance 是 XrInstance 的句柄。
  • systemId 是要枚举其空间功能特性的 XrSystemId。
  • capability 是将要枚举其功能的 XrSpatialCapabilityEXT。
  • capabilityFeatureCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • capabilityFeatureCountOutput 是特征数量；若 capabilityFeatureCapacityInput 容量不足，则为所需的容量。
  • capabilityFeatures 是一个 XrSpatialCapabilityFeatureEXT 数组。如果 capabilityFeatureCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 capabilityFeatures 大小，请参阅缓冲区大小参数部分。

应用使用 xrEnumerateSpatialCapabilityFeaturesEXT 发现给定系统针对 XrSpatialCapabilityEXT 支持的功能。

对于具有公开功能的能力，应用会选择要启用的功能，并在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中的能力配置结构链的下一个结构中提供相应的配置结构。

如果 capability 不是 xrEnumerateSpatialCapabilitiesEXT 枚举的功能，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。

运行时不得枚举未为 instance 启用扩展的空间功能。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

空间上下文

创建空间上下文

XR_DEFINE_HANDLE(XrSpatialContextEXT)

XrSpatialContextEXT 句柄表示用于在用户环境中发现和更新一定数量的空间实体的资源。应用可以使用此句柄，通过此扩展程序中的其他函数来发现和更新空间实体。

xrCreateSpatialContextAsyncEXT 函数定义如下：

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

参数说明

  • session 是一个 XrSession，空间上下文将在其中处于活跃状态。
  • createInfo 是用于指定空间上下文参数的 XrSpatialContextCreateInfoEXT。
  • future 是一个指向 XrFutureEXT 的指针。

应用可以通过以下方式创建 XrSpatialContextEXT 句柄：

如果 XrSpatialContextCreateInfoEXT ::capabilityConfigCount 为 0，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。空间上下文句柄至少需要一项功能。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 数组中的任何功能未被 xrEnumerateSpatialCapabilitiesEXT 枚举，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中的任何 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount 为 0，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。如果功能配置中没有列出要为该功能启用的组件类型，则该配置不完整。

如果 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 中列出的任何组件类型未在 xrEnumerateSpatialCapabilityComponentTypesEXT 中针对 XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability 进行枚举，则运行时必须返回 XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的下一个链中的任何结构对应于未在 xrEnumerateSpatialCapabilityFeaturesEXT 中为该功能枚举的 XrSpatialCapabilityFeatureEXT，则运行时必须忽略该 XrSpatialCapabilityFeatureEXT 结构。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 包含多个具有相同 XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability 的结构，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。

为确保以最佳方式使用系统资源，运行时可以使用 XrSpatialContextCreateInfoEXT 数组中提供的配置，为即将到来的空间请求做好准备。例如，如果应用创建了包含平面跟踪功能的空间上下文句柄，则支持平面跟踪功能的运行时可能只会启动其平面跟踪流水线。如果配置的功能需要较长的预热时间，则调用 xrCreateSpatialDiscoverySnapshotAsyncEXT 可能会导致快照为空。应用可以等待 XrEventDataSpatialDiscoveryRecommendedEXT，然后再使用 xrCreateSpatialDiscoverySnapshotAsyncEXT，以确保底层跟踪服务已预热。

如果运行时强制执行权限系统来控制应用对正在为 XrSpatialContextEXT 配置的空间功能的访问权限，那么当这些权限尚未授予此应用时，运行时必须返回 XR_ERROR_PERMISSION_INSUFFICIENT。

此函数会启动异步操作并创建相应的 XrFutureEXT，可与 xrPollFutureEXT 及相关函数搭配使用。此函数的返回值仅表示参数是否可用于安排异步操作。相应的完成函数为 xrCreateSpatialContextCompleteEXT，当此函数的 future 处于 READY 状态时，该函数会在完成结构 XrCreateSpatialContextCompletionEXT 中填充输出。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_TIME_INVALID（如果 XR_ANDROID_spatial_annotation_tracking 已启用）

XrSpatialContextCreateInfoEXT 结构定义如下：

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • capabilityConfigCount 是一个 uint32_t，用于描述 capabilityConfigs 数组中的元素数量。
  • capabilityConfigs 是一个指向 XrSpatialCapabilityConfigurationBaseHeaderEXT 指针数组的指针。

XrSpatialContextCreateInfoEXT 结构描述了用于创建 XrSpatialContextEXT 句柄的信息。

有效用法（隐式）

XrSpatialCapabilityConfigurationBaseHeaderEXT 结构的定义如下：

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

此结构不会直接在 API 中使用，但其子结构可以与 XrSpatialContextCreateInfoEXT 搭配使用，以配置空间功能。

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • capability 是 XrSpatialCapabilityEXT。
  • enabledComponentCount 是一个 uint32_t，用于描述 enabledComponents 数组中的元素数量。
  • enabledComponents 是一个指向 XrSpatialComponentTypeEXT 数组的指针。

如果 capability 未由 xrEnumerateSpatialCapabilitiesEXT 枚举，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。如果 enabledComponents 中列出的任何组件类型未在 xrEnumerateSpatialCapabilityComponentTypesEXT 中为 capability 枚举，则运行时必须返回 XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT。

有效用法（隐式）

xrCreateSpatialContextCompleteEXT 函数定义如下：

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

参数说明

xrCreateSpatialContextCompleteEXT 会完成由 xrCreateSpatialContextAsyncEXT 启动的异步操作。如果 future 未处于就绪状态，则运行时必须返回 XR_ERROR_FUTURE_PENDING_EXT。如果 future 已完成或已取消，则运行时必须返回 XR_ERROR_FUTURE_INVALID_EXT。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

XrCreateSpatialContextCompletionEXT 结构的定义如下：

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

成员说明

未来返回代码

futureResult 个值：

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

如果 futureResult 是成功代码，则 spatialContext 必须有效。如果 spatialContext 有效，则它仅在 xrCreateSpatialContextAsyncEXT :: session 的生命周期内有效，或者在应用使用 xrDestroySpatialContextEXT 销毁 spatialContext 之前有效，以先到者为准。

有效用法（隐式）

销毁空间上下文

xrDestroySpatialContextEXT 函数定义如下：

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

参数说明

应用在完成空间实体发现和更新任务后，可以调用 xrDestroySpatialContextEXT 函数来释放 spatialContext 句柄和底层资源。如果不存在其他使用与 spatialContext 相同的空间功能创建的有效 XrSpatialContextEXT，此调用会向运行时建议停用这些功能所需的跟踪服务，以节省系统资源。

有效用法（隐式）

线程安全

  • 对 spatialContext 及其任何子句柄的访问都必须在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

空间实体表示

空间实体 ID

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT 用于表示运行时在用户空间环境中发现的任何类型的实体。XrSpatialEntityIdEXT 在发现它的 XrSpatialContextEXT 中有效，并且运行时不得在同一 XrSpatialContextEXT 中为不同实体重复使用相同的 XrSpatialEntityIdEXT。此外，无论 表示的是相同实体还是不同实体，运行时都不得在同一 XrSession 中的多个 XrSpatialContextEXT 之间重复使用相同的 XrSpatialEntityIdEXT。

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT 是一个预留值，表示无效的 XrSpatialEntityIdEXT。只有在明确允许的情况下，才能将其传递给 API 函数并从 API 函数返回。

空间实体句柄

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

XrSpatialEntityEXT 句柄表示空间实体。应用可以创建此类句柄，以向运行时表达其对特定实体的兴趣。

通过 ID 创建空间实体句柄

xrCreateSpatialEntityFromIdEXT 函数的定义如下：

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

参数说明

应用可以使用 xrCreateSpatialEntityFromIdEXT 创建 XrSpatialEntityEXT 句柄，该句柄是对用户环境中存在的实体的引用。

如果 XrSpatialEntityFromIdCreateInfoEXT :: entityId 不是 spatialContext 的有效 ID，则运行时必须返回 XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialEntityFromIdCreateInfoEXT 结构定义如下：

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • entityId 是应用要为其创建句柄的实体的 XrSpatialEntityIdEXT。

有效用法（隐式）

销毁空间实体句柄

xrDestroySpatialEntityEXT 函数定义如下：

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

参数说明

当应用不再对 spatialEntity 句柄引用的实体感兴趣时，可以使用 xrDestroySpatialEntityEXT 释放该句柄。

有效用法（隐式）

线程安全

  • 对 spatialEntity 及其任何子句柄的访问都必须在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

空间快照

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

应用可以创建空间快照，以便发现空间实体或更新其关于已知空间实体的信息。XrSpatialSnapshotEXT 句柄表示已发现或已更新的空间实体及其部分组件（由应用选择）的不可变数据。空间快照表示实体及其组件数据的一致视图。创建快照后，快照的数据在有效期间必须保持不变。

应用可以根据需要创建任意数量的快照，但必须注意为每个新快照分配的内存，并且在不再需要快照时必须将其销毁。

创建发现快照

xrCreateSpatialDiscoverySnapshotAsyncEXT 函数定义如下：

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

参数说明

应用可以通过使用 xrCreateSpatialDiscoverySnapshotAsyncEXT 创建发现快照来发现空间实体。

此函数会启动异步操作并创建相应的 XrFutureEXT，可与 xrPollFutureEXT 及相关函数搭配使用。此函数的返回值仅表示参数是否可用于安排异步操作。对应的完成函数为 xrCreateSpatialDiscoverySnapshotCompleteEXT，当此函数的 future 处于 READY 状态时，该函数会在完成结构 XrCreateSpatialDiscoverySnapshotCompletionEXT 中填充输出。

应用可以提交多个发现快照创建请求，而无需等待上一个请求完成。运行时可以按任意顺序处理和完成快照创建。如果运行时需要根据设备的电源、散热或其他政策减少系统资源的使用，则可以延迟完成发现快照创建，以限制应用。

应用可以使用 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 来过滤实体列表以及运行时必须在快照中包含其数据的组件。如果应用在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中提供了有效的空间组件类型列表，则运行时必须仅在快照中包含具有 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中提供的至少一个组件的空间实体。此外，运行时必须仅包含快照中这些组件的数据。

如果 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中的任何 XrSpatialComponentTypeEXT 未针对创建 spatialContext 时传递给 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空间功能启用，则运行时必须返回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。

如果应用未在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中提供空间组件类型列表，则运行时必须在快照中包含所有空间实体，这些实体具有在 XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents 中为 spatialContext 配置的功能枚举的组件集。运行时必须包含为 spatialContext 配置的功能的所有已启用组件的数据。

如果 XrEventDataReferenceSpaceChangePending 在 future 完成之前排队，并且 XrEventDataReferenceSpaceChangePending :: poseValid 为 false，则运行时可以创建一个不包含任何实体的 XrSpatialSnapshotEXT，或者在 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time 处将 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 中无法再定位的实体的 XrSpatialEntityTrackingStateEXT 设置为 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT。运行时不得因 XrEventDataReferenceSpaceChangePending 而将 XrCreateSpatialContextCompletionEXT :: futureResult 设置为错误代码。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialDiscoverySnapshotCreateInfoEXT 结构定义如下：

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • componentTypeCount 是一个 uint32_t，用于描述 componentTypes 数组中的元素数量。
  • componentTypes 是一个 XrSpatialComponentTypeEXT 数组。

XrSpatialDiscoverySnapshotCreateInfoEXT 结构描述了在发现空间实体时创建 XrSpatialSnapshotEXT 句柄所需的信息。

有效用法（隐式）

xrCreateSpatialDiscoverySnapshotCompleteEXT 函数定义如下：

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

参数说明

xrCreateSpatialDiscoverySnapshotCompleteEXT 用于完成由 xrCreateSpatialDiscoverySnapshotAsyncEXT 启动的异步操作。如果 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future 未处于就绪状态，则运行时必须返回 XR_ERROR_FUTURE_PENDING_EXT。如果 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future 已完成或已取消，则运行时必须返回 XR_ERROR_FUTURE_INVALID_EXT。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrCreateSpatialDiscoverySnapshotCompletionInfoEXT 结构定义如下：

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

成员说明

所创建快照中包含的各种组件数据的位置将以 baseSpace 表示，位于 time。

有效用法（隐式）

XrCreateSpatialDiscoverySnapshotCompletionEXT 结构定义如下：

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • futureResult 是空间发现快照创建操作的 XrResult。
  • snapshot 是一个 XrSpatialSnapshotEXT，可用于查询所发现空间实体的组件数据。

未来返回代码

futureResult 个值：

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

有效用法（隐式）

发现推荐事件

XrEventDataSpatialDiscoveryRecommendedEXT 结构定义如下：

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • spatialContext 是运行时推荐进行发现的 XrSpatialContextEXT。

应用可以使用 xrPollEvent 检索此事件。应用可以通过等待此事件，避免过度调用 xrCreateSpatialDiscoverySnapshotAsyncEXT 来发现空间实体。如果应用在两个 XrEventDataSpatialDiscoveryRecommendedEXT 事件之间使用相同的 XrSpatialDiscoverySnapshotCreateInfoEXT 创建多个发现快照，则生成的快照可能包含相同的实体，因此快照创建和数据查询会造成浪费。

等待此事件创建新的发现快照可确保应用不会因发现请求而使系统过载，因为运行时可能不会返回任何新数据，这有助于避免过度使用系统资源的风险，并避免因设备的电源或热政策而受到限制。这也有助于在以下两种运行时之间实现一致性：一种是使用实时跟踪功能动态发现空间实体的运行时，另一种是根据先前记录的状态提供空间实体的运行时（其中运行时可能仅针对每个 XrSpatialContextEXT 将发现建议事件排队一次）。

运行时不得将此事件加入队列，以通知应用现有空间实体的组件数据发生了更改或调整。应用可以使用 xrCreateSpatialUpdateSnapshotEXT 跟踪其感兴趣的空间实体的组件数据更新。

运行时可以将发现建议事件加入队列，而无需等待应用先调用 xrCreateSpatialDiscoverySnapshotAsyncEXT。例如，运行时可以根据 XrSpatialContextEXT 的配置、其自身对用户周围环境的理解（发现新实体或丢失现有实体），或为了向应用提示适当的发现请求节奏以免系统资源过载，来决定是否将发现建议事件加入队列。如果 XrSpatialContextEXT 的整个生命周期内未在用户环境中找到任何实体，则运行时可能会选择不将此事件加入 XrSpatialContextEXT 的队列。

在应用使用 xrCreateSpatialContextCompleteEXT 完成创建之前，运行时不得将给定 spatialContext 的此事件加入队列。

在应用调用 xrDestroySpatialContextEXT 后，运行时不得再将该空间上下文的任何发现建议事件加入队列，也不得从 xrPollEvent 返回该上下文的任何此类事件。

有效用法（隐式）

查询组件数据

xrQuerySpatialComponentDataEXT 函数定义如下：

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

参数说明

应用可以使用 xrQuerySpatialComponentDataEXT 查询快照中实体的组件数据，方法是将列表结构附加到 XrSpatialComponentDataQueryResultEXT :: next，该结构对应于 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中的每个 XrSpatialComponentTypeEXT。

如果应用将列表结构附加到 XrSpatialComponentDataQueryResultEXT :: next，而该结构不对应于 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中列出的任何组件，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

应用可以选择仅附加与 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中列出的部分组件对应的列表结构。如果应用只想知道满足 queryCondition 的空间实体的 ID 和跟踪状态，则可以选择完全省略列表结构。运行时不得将 XrSpatialComponentDataQueryResultEXT :: next 链中缺少列表结构视为失败。

如果 XrEventDataReferenceSpaceChangePending 已加入队列，并且在应用从 XrSpatialSnapshotEXT 查询组件数据时 XrEventDataReferenceSpaceChangePending :: changeTime 已过去，则应用可以使用事件数据相应地调整姿势。

运行时必须仅使用具有 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中指定的所有组件的实体来填充 XrSpatialComponentDataQueryResultEXT :: entityIds。如果 XrSpatialComponentDataQueryConditionEXT :: componentTypeCount 为 0，则运行时必须使用快照中的所有实体（及其跟踪状态）填充 queryResult。如果向 XrSpatialComponentDataQueryConditionEXT :: next 添加了其他查询条件，则运行时必须将这些条件与组件类型可用性视为“AND”关系，即运行时必须仅使用满足所有提供条件的实体来填充 XrSpatialComponentDataQueryResultEXT ::entityIds。运行时必须按照 XrSpatialComponentDataQueryResultEXT :: entityIds 中实体的顺序，在列表结构中填充组件数据，即列表结构数组中给定索引处的组件数据必须与同一索引处的实体相对应。

如果实体的跟踪状态不是 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT，则运行时不得更改 XrSpatialComponentDataQueryResultEXT 附加的列表结构中包含的数组中与该实体对应的索引处的数据。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

例如，应用创建了一个包含 5 个实体的 XrSpatialSnapshotEXT，其中：

  • 实体 1 和 2 具有组件 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • 实体 3 和 4 具有组件 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • 实体 5 具有组件 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT。

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

是

是

是

是

否

否

否

否

是

是

家长

家长

是

是

是

是

否

否

否

否

否

否

Mesh3D

Mesh3D

否

否

否

否

是

是

是

是

是

是

Bounded3D

Bounded3D

否

否

否

否

是

是

是

是

否

否文本不是 SVG - 无法显示

图 20. 示例快照

在上述快照上调用 xrQuerySpatialComponentDataEXT，并在查询条件中列出 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT，将导致实体 #1、#2 和 #5 返回到应用，并且应用可以将 XrSpatialBounded2DDataEXT 数组作为 XrSpatialComponentBounded2DListEXT 结构的一部分附加到 XrSpatialComponentDataQueryResultEXT 的下一个链，以获取 bounded2D 数据。

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

entityId #1 的数据

实体的数据…

entityId #2 的数据

实体的数据…

entityId #5 的数据

实体的数据…

entityIds

entityIds

下一页

下一页

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat…

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou… 文本不是 SVG - 无法显示

图 21. 查询结果示例

在上述快照上调用 xrQuerySpatialComponentDataEXT，并在查询条件中列出 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件，将导致实体 #3 和 #4 返回给应用，并且应用可以将 XrBoxf 和 XrSpatialMeshDataEXT 数组分别作为 XrSpatialComponentBounded3DListEXT 和 XrSpatialComponentMesh3DListEXT 结构的一部分附加到 XrSpatialComponentDataQueryResultEXT 的下一个链，以获取组件数据。

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

entityId #3 的数据

实体的数据…

实体 ID #4 的数据

实体的数据…

Mesh3D

Mesh3D

entityId #3 的数据

实体的数据…

实体 ID #4 的数据

实体的数据…

entityIds

entityIds

下一页

下一页

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da…

bounds

bounds

下一页

下一页

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo…

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me…

网格

meshes Text is not SVG - cannot display

图 22. 查询结果示例

XrSpatialComponentDataQueryConditionEXT 结构的定义如下：

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • componentTypeCount 是一个 uint32_t，用于描述 componentTypes 数组中的元素数量。
  • componentTypes 是一个 XrSpatialComponentTypeEXT 数组，用于指定要从快照中获取哪些类型的数据。

有效用法（隐式）

XrSpatialComponentDataQueryResultEXT 结构的定义如下：

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • entityIdCapacityInput 是 entityIds 数组的容量，或设为 0 以请求获取所需的容量。
  • entityIdCountOutput 是 entityIds 中的 XrSpatialEntityIdEXT 数量；若 entityIdCapacityInput 容量不足，则为所需的容量。
  • entityIds 是 XrSpatialEntityIdEXT 数组。如果 entityIdCapacityInput 为 0，它可以为 NULL。
  • entityStateCapacityInput 是 entityStates 数组的容量，或设为 0 以请求获取所需的容量。
  • entityStateCountOutput 是 entityStates 中 XrSpatialEntityTrackingStateEXT 的数量；若 entityStateCapacityInput 容量不足，则为所需的容量。此值必须始终与 entityIdCountOutput 相同。
  • entityStates 是一个 XrSpatialEntityTrackingStateEXT 数组。如果 entityStateCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 entityIds 大小，请参阅缓冲区大小参数部分。

应用可以将 entityIds 与 xrCreateSpatialEntityFromIdEXT 搭配使用，为它希望定期更新的实体创建 XrSpatialEntityEXT 句柄。然后，应用可以将这些 XrSpatialEntityEXT 句柄与 xrCreateSpatialUpdateSnapshotEXT 搭配使用，以创建更新快照，其中包含运行时最新已知的所提供实体组件数据。

有效用法（隐式）

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

XrSpatialEntityTrackingStateEXT 枚举了可能的空间实体跟踪状态：

这些枚举具有以下含义：

枚举说明

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

运行时已停止跟踪此实体，且绝不会恢复跟踪。

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

运行时已暂停跟踪此实体，但可能会在未来恢复跟踪。

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

运行时当前正在跟踪此实体，并且其组件数据有效。

跟踪

已暂停

已停止

图 23. XrSpatialEntityTrackingStateEXT

  • 如果运行时暂停对空间实体的跟踪，但未来有可能恢复跟踪，则可能会将空间实体的状态从 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT 更改为 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT。运行时可能会执行此操作的一些示例包括（但不限于）：应用失去输入焦点；给定空间实体距离用户太远，无法准确跟踪；或者跟踪的实体太多，运行时想要降低跟踪成本。XrSpatialEntityTrackingStateEXT 可帮助应用免受每个运行时不同跟踪政策的影响。
  • 运行时可能会将实体的状态从 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 更改为 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT。
  • 如果空间实体丢失且其跟踪永远无法恢复或继续，则运行时必须将空间实体的状态从 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 更改为 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT。例如，如果设备失去跟踪，重启其跟踪会话，但无法在其环境中重新定位，因此会将此跟踪会话中发现的实体视为新实体。
  • 一旦实体的跟踪状态设置为 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT，运行时不得将其更改为任何其他状态。
  • 使用 xrQuerySpatialComponentDataEXT 查询空间实体的组件数据时，如果实体状态为 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT，则运行时必须在 XrSpatialComponentDataQueryResultEXT 的下一个链中，在应用提供的缓冲区内容中设置有效数据。如果实体状态为 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT，则运行时不得更改缓冲区的内容。

组件数据的双调用惯用法

XrSpatialBufferEXT 结构定义如下：

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

成员说明

  • bufferId 缓冲区数据的 XrSpatialBufferIdEXT。
  • bufferType 是 XrSpatialBufferTypeEXT，用于指示 bufferId 中的数据类型。应用可以使用 bufferType 来确定要使用哪个函数来检索缓冲区的实际数据。

某些空间组件具有可变大小的数据，因此需要使用两次调用惯用法来检索其数据。在这种情况下，空间组件数据结构会为该组件数据中所需的每个可变大小缓冲区提供一个 XrSpatialBufferEXT。

对于同一 bufferId，运行时必须在不同的组件数据查询之间提供相同的数据，即使跨越不同的快照也是如此。如果组件数据查询调用之间的 bufferId 不同，则向应用表明该组件的数据可能已更改。

有效用法（隐式）

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT 用于表示空间组件的任何类型的可变大小数据。

运行时必须将 XrSpatialBufferIdEXT 及其数据保留在内存中，至少保留到包含它的 XrSpatialSnapshotEXT 的生命周期结束。运行时可能会将 XrSpatialBufferIdEXT 及其数据保留在内存中的时间超过 XrSpatialSnapshotEXT 的生命周期，以便返回与应用稍后创建的快照相同的 ID。对于同一 XrSpatialBufferIdEXT，运行时必须始终通过适当的 xrGetSpatialBuffer* 函数返回相同的数据。

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

XrSpatialBufferTypeEXT 枚举用于标识 XrSpatialBufferIdEXT 表示的缓冲区的不同数据类型。

枚举说明

xrGetSpatialBufferStringEXT 函数定义如下：

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是字符数；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是 char 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以通过使用 xrGetSpatialBufferStringEXT 获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_STRING_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_STRING_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

由运行时填充的 buffer 必须是以 null 结尾的 UTF-8 字符串。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能调用 xrGetSpatialBufferStringEXT
  • snapshot 必须是有效的 XrSpatialSnapshotEXT 句柄
  • info 必须是指向有效 XrSpatialBufferGetInfoEXT 结构的指针
  • bufferCountOutput 必须是指向 uint32_t 值的指针
  • 如果 bufferCapacityInput 不是 0，则 buffer 必须是指向 bufferCapacityInput 个字符值数组的指针

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

xrGetSpatialBufferUint8EXT 函数定义如下：

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是 buffer 数组中的元素数量；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是 uint8_t 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以使用 xrGetSpatialBufferUint8EXT 获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能调用 xrGetSpatialBufferUint8EXT
  • snapshot 必须是有效的 XrSpatialSnapshotEXT 句柄
  • info 必须是指向有效 XrSpatialBufferGetInfoEXT 结构的指针
  • bufferCountOutput 必须是指向 uint32_t 值的指针
  • 如果 bufferCapacityInput 不是 0，则 buffer 必须是指向 bufferCapacityInput uint8_t 值数组的指针

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

xrGetSpatialBufferUint16EXT 函数定义如下：

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是 buffer 数组中的元素数量；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是 uint16_t 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_UINT16_EXT，方法是使用 xrGetSpatialBufferUint16EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_UINT16_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能调用 xrGetSpatialBufferUint16EXT
  • snapshot 必须是有效的 XrSpatialSnapshotEXT 句柄
  • info 必须是指向有效 XrSpatialBufferGetInfoEXT 结构的指针
  • bufferCountOutput 必须是指向 uint32_t 值的指针
  • 如果 bufferCapacityInput 不是 0，则 buffer 必须是指向 bufferCapacityInput uint16_t 值数组的指针

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

xrGetSpatialBufferUint32EXT 函数定义如下：

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是 buffer 数组中的元素数量；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是 uint32_t 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以使用 xrGetSpatialBufferUint32EXT 获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能调用 xrGetSpatialBufferUint32EXT
  • snapshot 必须是有效的 XrSpatialSnapshotEXT 句柄
  • info 必须是指向有效 XrSpatialBufferGetInfoEXT 结构的指针
  • bufferCountOutput 必须是指向 uint32_t 值的指针
  • 如果 bufferCapacityInput 不是 0，则 buffer 必须是指向 bufferCapacityInput uint32_t 值数组的指针

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

xrGetSpatialBufferFloatEXT 函数定义如下：

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是 buffer 数组中的元素数量；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是 float 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以通过使用 xrGetSpatialBufferFloatEXT 获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能调用 xrGetSpatialBufferFloatEXT
  • snapshot 必须是有效的 XrSpatialSnapshotEXT 句柄
  • info 必须是指向有效 XrSpatialBufferGetInfoEXT 结构的指针
  • bufferCountOutput 必须是指向 uint32_t 值的指针
  • 如果 bufferCapacityInput 不是 0，则 buffer 必须是指向 bufferCapacityInput float 值数组的指针

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

xrGetSpatialBufferVector2fEXT 函数定义如下：

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是 buffer 数组中的元素数量；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是 XrVector2f 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以通过使用 xrGetSpatialBufferVector2fEXT 获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

xrGetSpatialBufferVector3fEXT 函数定义如下：

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

参数说明

  • snapshot 是 XrSpatialSnapshotEXT 的句柄。
  • info 包含要查询的缓冲区的信息。
  • bufferCapacityInput 是数组的容量，或设为 0 以请求获取所需的容量。
  • bufferCountOutput 是 buffer 数组中的元素数量；若 bufferCapacityInput 容量不足，则为所需的容量。
  • buffer 是一个 XrVector3f 数组。如果 bufferCapacityInput 为 0，它可以为 NULL。
  • 如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

应用可以通过使用 xrGetSpatialBufferVector3fEXT 获取组件提供的 XrSpatialBufferEXT 的数据，其中 XrSpatialBufferEXT :: bufferType 为 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不属于 snapshot，则运行时必须返回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialBufferGetInfoEXT 结构的定义如下：

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • bufferId：要检索其数据的缓冲区的 XrSpatialBufferIdEXT。

有效用法（隐式）

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT 是一个预留值，表示无效的 XrSpatialBufferIdEXT。只有在明确允许的情况下，它才可以传递给 API 函数并由 API 函数返回。

创建更新快照

xrCreateSpatialUpdateSnapshotEXT 函数定义如下：

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

参数说明

应用可以使用 xrCreateSpatialUpdateSnapshotEXT 创建快照，并获取运行时已知的特定实体的最新组件数据。应用可以在创建快照时提供 XrSpatialEntityEXT 句柄及其感兴趣的组件类型。

应用可以使用 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 过滤其数据必须包含在快照中的组件列表。如果应用在 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中提供了有效的空间组件类型列表，则运行时必须仅在快照中包含至少具有 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中提供的组件之一的空间实体。此外，运行时必须仅包含快照中这些组件的数据。

如果 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中的任何 XrSpatialComponentTypeEXT 未针对创建 spatialContext 时传递给 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空间功能启用，则运行时必须返回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。

如果应用未在 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中提供空间组件类型列表，则运行时必须在快照中包含 XrSpatialUpdateSnapshotCreateInfoEXT :: entities 中列出的所有空间实体，并且必须包含为 spatialContext 配置的功能的所有已启用组件的数据。

运行时不得包含 snapshot 中的 XrSpatialUpdateSnapshotCreateInfoEXT :: entities 中未列出的空间实体。

应用可以根据需要创建任意数量的快照，但必须注意为每个新快照分配的内存，并且在不再需要快照时必须将其销毁。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialUpdateSnapshotCreateInfoEXT 结构的定义如下：

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • entityCount 是一个 uint32_t，用于描述 entities 数组中的元素数量。
  • entities 是一个 XrSpatialEntityEXT 数组，运行时必须在快照中包含这些实体的组件数据。
  • componentTypeCount 是一个 uint32_t，用于描述 componentTypes 数组中的元素数量。
  • componentTypes 是一个 XrSpatialComponentTypeEXT 数组，运行时必须在快照中包含这些类型的数据。
  • baseSpace 是 XrSpace，更新后的 XrSpatialSnapshotEXT 的所有位置都将相对于该空间进行定位。
  • time 是 XrTime，更新后的 XrSpatialSnapshotEXT 的所有位置都将位于该时间。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能使用 XrSpatialUpdateSnapshotCreateInfoEXT
  • type 必须为 XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next 必须为 NULL 或指向结构链中下一个结构的有效指针
  • entities 必须是指向包含 entityCount 个有效 XrSpatialEntityEXT 句柄的数组的指针
  • 如果 componentTypeCount 不为 0，则 componentTypes 必须是指向包含 componentTypeCount 个有效 XrSpatialComponentTypeEXT 值的数组的指针
  • baseSpace 必须是有效的 XrSpace 句柄
  • entityCount 参数必须大于 0
  • baseSpace 和 entities 的元素必须已从同一 XrSession 创建、分配或检索

销毁快照

xrDestroySpatialSnapshotEXT 函数定义如下：

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

参数说明

应用可以调用 xrDestroySpatialSnapshotEXT 来销毁 XrSpatialSnapshotEXT 句柄及其关联的资源。

有效用法（隐式）

线程安全

  • 对 snapshot 及其任何子句柄的访问都必须在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

常见组件

有界 2D

组件数据

XrSpatialBounded2DDataEXT 结构的定义如下：

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

成员说明

  • center 是一个 XrPosef，用于定义有界 2D 组件的几何中心。
  • extents 是有界 2D 组件沿 x 轴 (extents.width) 和 y 轴 (extents.height) 的范围，以 center 为中心。

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 的 extents 是指实体在平面坐标系的 x-y 平面中的大小。位置为 {0, 0, 0}、旋转为 {0, 0, 0, 1}（无旋转）且范围为 {1, 1} 的平面是指以 {0, 0, 0} 为中心、尺寸为 1 米 x 1 米的平面，其正面法向量指向组件空间中的 +Z 方向。

X X Y Y Z Z 高度 高度 Y Y Z Z X X 垂直平面 垂直平面 水平平面 水平平面 宽度 宽度 宽度 宽度 高度 高度

图 24. Bounded2D 组件坐标系

注意

OpenXR 使用 X-Y 平面，其中 +Z 为平面法线，但其他 API 可能使用 X-Z 平面，其中 +Y 为平面法线。通过围绕 +X 轴旋转 -π/2 弧度，可以将 X-Y 平面转换为 X-Z 平面。

有效用法（隐式）

用于查询数据的组件列表结构

XrSpatialComponentBounded2DListEXT 结构的定义如下：

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • boundCount 是一个 uint32_t，用于描述 bounds 数组中的元素数量。
  • bounds 是一个 XrSpatialBounded2DDataEXT 数组。

如果 XrSpatialComponentBounded2DListEXT 位于 XrSpatialComponentDataQueryResultEXT :: next 的下一个链中，但 XrSpatialComponentDataQueryConditionEXT ::componentTypeCount 不为零，且 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_VALIDATION_FAILURE。

如果 boundCount 小于 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_SIZE_INSUFFICIENT。

如果 xrQuerySpatialComponentDataEXT :: snapshot 是通过 xrCreateSpatialDiscoverySnapshotCompleteEXT 创建的，则运行时必须在 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 和 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time 中提供 XrSpatialBounded2DDataEXT :: center。

如果 xrQuerySpatialComponentDataEXT :: snapshot 是通过 xrCreateSpatialUpdateSnapshotEXT 创建的，则运行时必须在 XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace 和 XrSpatialUpdateSnapshotCreateInfoEXT :: time 中提供 XrSpatialBounded2DDataEXT :: center。

有效用法（隐式）

配置

如果 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中添加枚举值来启用该功能。此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。

有界 3D

组件数据

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 使用 XrBoxf 存储其数据。

用于查询数据的组件列表结构

XrSpatialComponentBounded3DListEXT 结构的定义如下：

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • boundCount 是一个 uint32_t，用于描述 bounds 数组中的元素数量。
  • bounds 是 XrBoxf 数组。

如果 XrSpatialComponentBounded3DListEXT 位于 XrSpatialComponentDataQueryResultEXT :: next 的下一个链中，但 XrSpatialComponentDataQueryConditionEXT ::componentTypeCount 不为零，且 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_VALIDATION_FAILURE。

如果 boundCount 小于 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_SIZE_INSUFFICIENT。

如果 xrQuerySpatialComponentDataEXT :: snapshot 是通过 xrCreateSpatialDiscoverySnapshotCompleteEXT 创建的，则运行时必须在 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 的 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time 中提供 XrBoxf :: center。

如果 xrQuerySpatialComponentDataEXT :: snapshot 是通过 xrCreateSpatialUpdateSnapshotEXT 创建的，则运行时必须在 XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace 的 XrSpatialUpdateSnapshotCreateInfoEXT :: time 处提供 XrBoxf :: center。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能使用 XrSpatialComponentBounded3DListEXT
  • type 必须为 XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
  • next 必须为 NULL 或指向结构链中下一个结构的有效指针
  • bounds 必须是指向 boundCount XrBoxf 结构数组的指针
  • boundCount 参数必须大于 0
配置

如果 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含该枚举来启用该功能。此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。

家长

组件数据

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 使用 XrSpatialEntityIdEXT 存储其数据。

用于查询数据的组件列表结构

XrSpatialComponentParentListEXT 结构的定义如下：

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • parentCount 是一个 uint32_t，用于描述 parents 数组中的元素数量。
  • parents 是 XrSpatialEntityIdEXT 数组。

如果 XrSpatialComponentParentListEXT 位于 XrSpatialComponentDataQueryResultEXT :: next 的下一个链中，但 XrSpatialComponentDataQueryConditionEXT ::componentTypeCount 不为零，且 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_VALIDATION_FAILURE。

如果 parentCount 小于 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_SIZE_INSUFFICIENT。

有效用法（隐式）

  • 必须先启用 XR_EXT_spatial_entity 扩展程序，然后才能使用 XrSpatialComponentParentListEXT
  • type 必须为 XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next 必须为 NULL 或指向结构链中下一个结构的有效指针
  • parents 必须是指向 parentCount XrSpatialEntityIdEXT 值数组的指针
  • parentCount 参数必须大于 0
配置

如果 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含该枚举来启用该功能。此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。

3D 网格

组件数据

XrSpatialMeshDataEXT 结构的定义如下：

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

成员说明

  • origin 是一个 XrPosef，定义了网格的原点。网格的所有顶点必须相对于此原点。
  • vertexBuffer 是一个 XrSpatialBufferEXT，用于提供缓冲区的 ID，该缓冲区表示此组件所在实体的顶点缓冲区。顶点的位置必须相对于 origin。
  • indexBuffer 是一个 XrSpatialBufferEXT，用于提供表示三角形索引数组的缓冲区的 ID，指定 vertexBuffer 中网格顶点的索引。必须按逆时针顺序返回三角形索引，并且三个索引表示一个三角形。

使用 XrSpatialMeshDataEXT 的组件类型必须指定 vertexBuffer 和 indexBuffer 的 XrSpatialBufferTypeEXT。

有效用法（隐式）

用于查询数据的组件列表结构

XrSpatialComponentMesh3DListEXT 结构的定义如下：

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • meshCount 是一个 uint32_t，用于描述 meshes 数组中的元素数量。
  • meshes 是一个 XrSpatialMeshDataEXT 数组。

应用可以查询 XrSpatialSnapshotEXT 中空间实体的网格 3D 组件，方法是在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中添加 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT，并将 XrSpatialComponentMesh3DListEXT 添加到 XrSpatialComponentDataQueryResultEXT 的下一个指针链。

如果 XrSpatialComponentMesh3DListEXT 位于 XrSpatialComponentDataQueryResultEXT :: next 的下一个链中，但 XrSpatialComponentDataQueryConditionEXT ::componentTypeCount 不为零，且 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_VALIDATION_FAILURE。

如果 meshCount 小于 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_SIZE_INSUFFICIENT。

对于由运行时在 meshes 数组中填充的 XrSpatialMeshDataEXT，XrSpatialMeshDataEXT :: vertexBuffer 的 XrSpatialBufferEXT :: bufferType 必须为 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT，XrSpatialMeshDataEXT :: indexBuffer 的 XrSpatialBufferEXT :: bufferType 必须为 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT。

有效用法（隐式）

配置

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过将该枚举包含在支持此组件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 派生结构的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中来启用该功能。

此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。

跟踪状态过滤条件

XrSpatialFilterTrackingStateEXT 结构的定义如下：

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

成员说明

应用可以在 XrSpatialDiscoverySnapshotCreateInfoEXT 的下一个链中使用 XrSpatialFilterTrackingStateEXT，将发现范围限定为跟踪状态为 trackingState 的实体。

应用可以在 XrSpatialComponentDataQueryConditionEXT 的下一个链中使用 XrSpatialFilterTrackingStateEXT，将快照中的组件数据查询范围限定为跟踪状态为 trackingState 的实体。

有效用法（隐式）

示例代码

应用使用情况

应用通常采用以下模式使用空间实体扩展：

发现空间实体并查询组件数据

以下示例代码演示了如何发现功能“Foo”的空间实体并查询其组件数据。

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

查询缓冲区数据

以下示例代码演示了如何获取提供 XrSpatialBufferEXT 的组件的数据。

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

扩展程序指南

语义标签设计和扩展指南

虽然此扩展程序未定义任何用于传达实体语义标签信息的组件，但它为定义此类组件的所有扩展程序制定了设计规则和指南。在以下文本中，“应该”和“必须”约束的是此类功能的作者，而不是运行时实现或使用该 API 的应用。

  • 如果某个扩展程序正在为任何 XrSpatialCapabilityEXT 定义语义标签，则应通过定义新的 XrSpatialComponentTypeEXT 以及包含一组标签（“语义标签集”）的新枚举来作为该组件的数据。
  • 表示语义标签集的枚举必须有一个值，用于指示实体未归入此集的任何标签。此枚举值的名称必须包含“UNCATEGORIZED”，例如 XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT。此值向应用表明，运行时确实能识别此实体，但此实体还归入了其他语义标签集。
  • 在 xrEnumerateSpatialCapabilityComponentTypesEXT 中枚举此新定义的 XrSpatialComponentTypeEXT 意味着运行时支持与该组件类型对应的语义标签集（以及该集中定义的标签）。
  • 应用通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 数组（该数组属于枚举了组件类型的功能的配置结构体）中添加相应的 XrSpatialComponentTypeEXT，来表达其希望发现具有属于此语义标签集的标签的实体。
  • 一个空间实体可能具有多个组件，每个组件都从其自己的语义标签集中为其提供一个标签。请考虑以下示例，其中包含一些假设的语义标签集 - XrSpatialObjectSemanticLabel，其值可能为椅子、沙发、桌子等，XrSpatialSofaBrand，其值可能是 IKEA、Wayfair 等；XrSpatialIkeaSofa，其值可能是 IKEA 沙发的具体型号名称。在这种情况下，同一个沙发实体具有所有 3 个组件（来自所有 3 个语义标签集的标签），每个组件都提供有关该实体的不同粒度的信息。
  • 如果某个扩展定义了一个新的 XrSpatialComponentTypeEXT，该类型提供了一个新的语义标签集，其中除了 UNCATEGORIZED 标签外还包含多个标签，则该扩展应考虑定义一个 XrSpatialCapabilityFeatureEXT，以便应用仅激活与该组件类型对应的语义标签集中定义的部分标签。此子集在功能配置的下一个链中提供，可作为提示，让运行时优化其跟踪流水线，并仅跟踪提供的子集。下文提供了一个此类功能结构体的示例。
  • 扩展程序不得向现有语义标签集枚举添加标签。相反，它们必须定义一个新的枚举，其中包含具有相同语义且值与另一组中的值相同的等效枚举，以及新添加的枚举。新定义的语义标签集的规范还必须建立旧标签集与新标签集之间的映射。请参阅下文中的示例。
语义标签子集的空间特征定义示例
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
空间语义标签扩展示例
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

以上述示例为例，其中扩展程序定义了枚举 XrSpatialExamplePlaneSemanticLabelExtensionEXT，以便使用值扩展现有的 XrSpatialPlaneSemanticLabelEXT，从而表示门窗。新枚举的规范必须包含以下形式的文本：

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

新宏

新基本类型

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

新对象类型

新增命令

新结构

新枚举

新枚举常量

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • 扩展 XrObjectType：

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • 扩展 XrResult：

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • 扩展 XrStructureType：

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

问题

  • 单个实体是否始终仅源自单一能力？

    • 已解决
    • 回答：否。这完全取决于运行时，具体取决于其自身的跟踪功能以及它希望如何表示检测到的实体。该规范不规定空间实体的任何特定表示形式，但规定了给定功能的保证组件，以设定最低预期。运行时可以合并由不同功能检测到的实体，并将其表示为单个实体，其中包含有助于识别该实体的所有功能的保证组件。例如，平面跟踪功能和对象跟踪功能都可以检测到桌子，其中平面跟踪功能在实体上提供 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 组件，而对象跟踪功能提供 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT。某些运行时可能会将该表作为 2 个单独的实体提供，每个实体都有自己的一组保证组件，而某些运行时可能仅提供 1 个实体来表示该表，并在同一实体上同时具有 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT。这里需要注意的重要一点是，对于任何给定的组件类型，一个空间实体最多只能有一个组件。因此，如果不同功能生成的组件数据对于某个实体存在冲突，则运行时必须将其表示为 2 个单独的实体。

版本历史记录

  • 修订版本 1，2024 年 4 月 12 日（Nihav Jain，Google）

    • 初始扩展程序说明