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 中场景理解和空间推理的概念和基础。这统一了几个相关但不同的功能领域，这些功能领域以该扩展程序定义的广泛统一的方式进行枚举、配置和交互。由于此扩展程序缺少上述任何功能领域的具体定义，因此正式规范文本往往有些抽象。本扩展规范文本中包含的示例有时会提及即将推出或假设的相关扩展中定义的功能，以进行说明，但不会固有地限制或指定此类附加功能。

此扩展程序的各个部分如下所示：

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

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

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

此扩展程序还定义了多个预计将在各种功能中使用的常见组件。

空间实体

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

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

通过操作系统公开的内容（例如控制器或眼球注视）不应建模为空间实体。

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

为空间实体提供二维边界多边形的组件。对应的列表结构为 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 扩展添加）

空间功能和设置

空间功能定义了运行时发现具有一组保证组件的实体的能力。应用在创建 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

能够检测和跟踪 Micro QR 码。（由 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);

参数说明

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

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

如果 xrEnumerateSpatialCapabilitiesEXT 未枚举 capability，则运行时必须返回 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。如果缺少要为相应功能启用的组件类型列表，功能配置就不完整。

如果 xrEnumerateSpatialCapabilityComponentTypesEXT 中未针对 XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability 枚举 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 中列出的任何组件类型，运行时必须返回 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

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 数组的指针。

如果 xrEnumerateSpatialCapabilitiesEXT 未枚举 capability，则运行时必须返回 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。此外，无论 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);

参数说明

当应用不再需要此句柄所引用的实体时，可以使用 xrDestroySpatialEntityEXT 来释放 spatialEntity 句柄。

有效使用情况（隐式）

线程安全

  • 对 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 中提供的组件之一的空间实体。此外，运行时必须仅在快照中包含这些组件的数据。

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

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

如果 XrEventDataReferenceSpaceChangePending 在 future 完成之前排队，并且 XrEventDataReferenceSpaceChangePending :: poseValid 为 false，则运行时可能会创建不包含任何实体的 XrSpatialSnapshotEXT，或者将 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 中不再可定位的实体的 XrSpatialEntityTrackingStateEXT 设置为 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time 中的 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

实体 ID 为 1 的数据

实体的数据…

实体 ID 为 2 的数据

实体的数据…

实体 ID 为 5 的数据

实体的数据…

entityIds

entityIds

下一页

下一页

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat…

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

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

图 21. 查询结果示例

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

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

实体 ID 为 3 的数据

实体的数据…

实体 ID 为 4 的数据

实体的数据…

Mesh3D

Mesh3D

实体 ID 为 3 的数据

实体的数据…

实体 ID 为 4 的数据

实体的数据…

entityIds

entityIds

下一页

下一页

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da…

bounds

bounds

下一页

下一页

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo…

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me…

网格

网格 文字不是 SVG - 无法显示

图 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 的生命周期结束。为了返回与应用稍后创建的快照相同的 ID，运行时可能会将 XrSpatialBufferIdEXT 及其数据保留在内存中的时间长于 XrSpatialSnapshotEXT 的生命周期。对于同一 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 大小，请参阅缓冲区大小参数部分。

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

如果 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 个 char 值数组的指针

返回代码

成功

  • 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。

有效使用情况（隐式）

  • 在调用 xrGetSpatialBufferUint32EXT 之前，必须启用 XR_EXT_spatial_entity 扩展程序
  • 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 大小，请参阅缓冲区大小参数部分。

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

如果 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 大小，请参阅缓冲区大小参数部分。

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

如果 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 中提供的组件之一的空间实体。此外，运行时必须仅在快照中包含这些组件的数据。

如果创建 spatialContext 时，传递给 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空间功能未启用 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中的任何 XrSpatialComponentTypeEXT，运行时必须返回 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 是所有更新 XrSpatialSnapshotEXT 的位置所在的 XrTime。

有效使用情况（隐式）

  • 必须先启用 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 轴（范围宽度）、y 轴（范围高度）的范围，以 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. 有界 2D 组件坐标系

注意

OpenXR 使用以 +Z 为平面法线的 X-Y 平面，但其他 API 可能使用以 +Y 为平面法线的 X-Z 平面。通过绕 +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。

有效使用情况（隐式）

配置

如果 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列举了某个功能，应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含相应枚举值来启用该功能。XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT此组件不需要任何特殊配置即可包含在下一个 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 中提供 XrBoxf :: center（位于 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time）。

如果 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
配置

如果 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某个功能枚举了 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT，应用可以通过在 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 的下一个链中，但 XrSpatialComponentDataQueryConditionEXT ::componentTypeCount 不为零，且 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，则运行时必须从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_VALIDATION_FAILURE。next

如果 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
配置

如果 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某个功能枚举了 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT，应用可以通过在 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 不为零，且 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中不包含 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT，则运行时必须从 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。

有效使用情况（隐式）

配置

如果 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某个功能枚举了 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT，则应用可以通过将该枚举包含在支持相应组件的功能的 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）

    • 初始扩展程序说明