XR_EXT_spatial_mesh_tracking

名称字符串

XR_EXT_spatial_mesh_tracking

扩展程序类型

实例扩展程序

已注册的扩展程序编号

784

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

XR_EXT_spatial_entity

创作贡献者

Nihav Jain，Google
Natalie Fleury，Meta
Yuichi Taguchi，Meta
Ron Bessems，Meta
Yin Li，Microsoft
Jimmy Alamparambil，ByteDance
Zhipeng Liu，ByteDance
Jun Yan，ByteDance

概览

此扩展程序基于 XR_EXT_spatial_entity 构建，定义了用于跟踪环境三角形网格的空间功能。此扩展程序中定义的功能提供的三角形网格旨在供应用使用，以确定虚拟内容与环境的碰撞。

空间网格跟踪功能

此扩展程序将 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 定义为一种空间功能，用于跟踪环境的三角形网格。此功能不涵盖跟踪平面和对象等实体的网格，而是必须通过枚举 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件来指示跟踪这些实体的相应功能。

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 用于向应用提供不透水和非不透水网格，具体取决于运行时的功能和应用选择的配置。

不透水网格是指所有尺寸的间隙和未扫描区域都已填充，并在特定体积块内形成紧密网格。顾名思义，如果应用在不透水网格内填充水，则不透水体积内不应有水漏出。使扫描网格不透水通常需要非常高的计算能力，不过一些运行时会通过预先处理网格来抵消该成本。

运行时支持

如果运行时支持跟踪环境的三角形网格，则必须通过在 xrEnumerateSpatialCapabilitiesEXT 中枚举 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 来指明这一点。

支持 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 的运行时可能具有以下 3 种能力：

配置

XrSpatialCapabilityConfigurationMeshTrackingEXT 结构定义如下：

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

成员说明

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

应用可以通过在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中添加指向 XrSpatialCapabilityConfigurationMeshTrackingEXT 结构的指针来启用 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 空间功能。

如果 capability 不是 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

有效用法（隐式）

跟踪封闭网格

XrSpatialFeatureTrackWatertightMeshEXT 结构的定义如下：

typedef struct XrSpatialFeatureTrackWatertightMeshEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           enableWatertightMeshTracking;
} XrSpatialFeatureTrackWatertightMeshEXT;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • enableWatertightMeshTracking 指示运行时是否必须为扫描的环境计算不透水网格。

支持不透水网格跟踪的运行时必须在 xrEnumerateSpatialCapabilityFeaturesEXT 中枚举 XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT。借助 XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT 功能，应用可以选择启用不透水网格跟踪，并明确选择加入不透水网格生成可能产生的任何额外计算。

如果 XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT 由 xrEnumerateSpatialCapabilityFeaturesEXT 针对某项功能进行枚举，则应用可以将 XrSpatialFeatureTrackWatertightMeshEXT 链接到该功能的相应配置结构，以指明是否希望跟踪的网格不透水。如果应用将 enableWatertightMeshTracking 设置为 XR_TRUE，则运行时必须计算并为应用提供环境的封闭网格。如果应用将 enableWatertightMeshTracking 设置为 XR_FALSE，则跟踪的网格可能仍是封闭的，前提是运行时仅支持封闭网格跟踪，例如，运行时提供来自预扫描环境的处理后网格。

有效用法（隐式）

应用流程

下图展示了应用如何配置空间上下文，以便跟踪环境的封闭网格。

是

是

应用需要
不透水网格

应用需要…

是

是

否

否

运行时
支持“网格跟踪”
功能

运行时…

是

是

否

否

运行时
支持“跟踪不透水网格”
功能

运行时…

应用通过“网格跟踪功能”和“跟踪不透水网格”功能创建空间上下文

应用会创建空间…

应用会处理当前运行时不支持功能的情况

应用会处理缺少…

应用会处理跟踪的网格，以自行创建封闭网格，可能需要用户协助修补网格中的孔洞

应用会处理 tr… 文本不是 SVG - 无法显示

图 29. 请求不透水网格的应用流程

保证型组件

支持 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 的运行时必须提供以下空间组件，作为此功能发现的所有实体的保证组件，并且必须在 xrEnumerateSpatialCapabilityComponentTypesEXT 中枚举这些组件：

  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
有界 3D 组件

有界 3D 组件提供其所在实体的中心和范围。此组件提供的数据使应用可以更轻松地剔除视锥体之外的实体。

如需了解详情，请参阅有界 3D。

网格 3D 组件

网格 3D 组件提供其所在实体的 3D 网格。如需了解详情，请参阅 Mesh 3D。

体积分割（分块）

运行时可以将网格分割成体积块（区块），以便应用更轻松地剔除其视锥体之外的网格块。在这种情况下，运行时必须将每个此类体积块视为一个单独的实体，并在每个此类实体（体积块）上提供一组保证组件。如果运行时以这种方式提供不透水网格，则每个体积块单独来看都不是不透水的，但一组块组合在一起会形成不透水网格。在这种情况下，运行时必须在每个实体（体积块）上添加 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 组件，并且共同形成不透水网格的各个块的父实体值必须相同。这样，应用就能识别哪些区块共同构成了一个封闭网格。

相邻体积块的网格可以共享顶点，但一个体积块的三角形不得与其相邻体积块的三角形重叠。

可选组件

网格法线

组件数据

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 使用 XrSpatialBufferEXT 来存储其数据。XrSpatialBufferEXT :: bufferId 表示包含此组件所在实体网格的顶点法线的缓冲区。XrSpatialBufferEXT :: bufferType 必须为 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT。具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 的实体必须同时具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT。此组件提供的法线必须与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件的 XrSpatialMeshDataEXT :: vertexBuffer 中提供的顶点相对应。

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

XrSpatialComponentMesh3DNormalsListEXT 结构的定义如下：

typedef struct XrSpatialComponentMesh3DNormalsListEXT {
    XrStructureType        type;
    void*                  next;
    uint32_t               meshNormalsCount;
    XrSpatialBufferEXT*    meshNormals;
} XrSpatialComponentMesh3DNormalsListEXT;

成员说明

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

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

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

有效用法（隐式）

配置

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含该枚举来启用该功能。此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。不过，我们建议应用将此组件及其数据与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件结合使用。

网格语义标签

typedef enum XrSpatialMeshSemanticLabelEXT {
    XR_SPATIAL_MESH_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_FLOOR_EXT = 2,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_WALL_EXT = 3,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_CEILING_EXT = 4,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_CHAIR_EXT = 6,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_SOFA_EXT = 7,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_BED_EXT = 8,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMeshSemanticLabelEXT;

XrSpatialMeshSemanticLabelEXT 枚举描述了网格的一组语义标签。不同的空间组件会使用此属性，为 XrSpatialBufferEXT 中每个顶点或每个三角形语义标签的 uint8_t 值赋予含义。请参阅网格顶点语义标签和网格三角形语义标签

如果扩展程序想要扩展此语义标签集或为网格添加自己的新集，应遵循语义标签设计和扩展指南中提供的指南。

枚举说明

XR_SPATIAL_MESH_SEMANTIC_LABEL_UNCATEGORIZED_EXT

运行时无法对顶点或三角形进行分类。

XR_SPATIAL_MESH_SEMANTIC_LABEL_FLOOR_EXT

顶点或三角形映射到楼层。

XR_SPATIAL_MESH_SEMANTIC_LABEL_WALL_EXT

顶点或三角形映射到墙壁。

XR_SPATIAL_MESH_SEMANTIC_LABEL_CEILING_EXT

顶点或三角形映射到天花板。

XR_SPATIAL_MESH_SEMANTIC_LABEL_TABLE_EXT

顶点或三角形会映射到表格。

XR_SPATIAL_MESH_SEMANTIC_LABEL_CHAIR_EXT

顶点或三角形映射到椅子。

XR_SPATIAL_MESH_SEMANTIC_LABEL_SOFA_EXT

顶点或三角形映射到沙发。

XR_SPATIAL_MESH_SEMANTIC_LABEL_BED_EXT

顶点或三角形映射到苗床。

网格顶点语义标签

组件概览

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 为空间实体网格的每个顶点提供一个语义标签。

组件数据

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 使用 XrSpatialBufferEXT 来存储其数据。XrSpatialBufferEXT :: bufferId 表示包含此组件所在实体网格的顶点语义标签的缓冲区。XrSpatialBufferEXT :: bufferType 必须为 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT。缓冲区中的值对应于 XrSpatialMeshSemanticLabelEXT 枚举的值。具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 的实体必须同时具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件。此组件提供的语义标签必须与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件的 XrSpatialMeshDataEXT :: vertexBuffer 中提供的顶点相对应。这意味着，此组件提供的空间缓冲区数据中给定索引处的语义标签对应于 XrSpatialMeshDataEXT :: vertexBuffer 提供的相同索引处的顶点。这也意味着，xrGetSpatialBufferUint8EXT :: bufferCountOutput 必须与顶点语义标签缓冲区和 XrSpatialMeshDataEXT :: vertexBuffer 的值相同。

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

XrSpatialComponentMesh3DVertexSemanticLabelsListEXT 结构的定义如下：

typedef struct XrSpatialComponentMesh3DVertexSemanticLabelsListEXT {
    XrStructureType        type;
    void*                  next;
    uint32_t               meshSemanticLabelsCount;
    XrSpatialBufferEXT*    meshSemanticLabels;
} XrSpatialComponentMesh3DVertexSemanticLabelsListEXT;

成员说明

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

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

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

有效用法（隐式）

配置

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含该枚举来启用该功能。此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。不过，我们建议应用将此组件及其数据与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件结合使用。此组件不能与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 一起启用。如果应用同时将 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 添加到 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。如果应用尝试在单独的 XrSpatialContextEXT 中同时启用这两个组件，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。

网格三角形语义标签

组件概览

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 为空间实体网格的每个三角形提供一个语义标签。

组件数据

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 使用 XrSpatialBufferEXT 来存储其数据。XrSpatialBufferEXT :: bufferId 表示包含此组件所在实体网格的三角形语义标签的缓冲区。XrSpatialBufferEXT :: bufferType 必须为 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT。缓冲区中的值对应于 XrSpatialMeshSemanticLabelEXT 枚举的值。具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 的实体必须同时具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件。此组件提供的语义标签必须与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件的 XrSpatialMeshDataEXT 中提供的三角形相对应。包含三角形语义标签的空间缓冲区的元素数量是 XrSpatialMeshDataEXT :: indexBuffer 的元素数量除以 3。这意味着，此组件提供的空间缓冲区数据中给定索引处的语义标签对应于 XrSpatialMeshDataEXT :: indexBuffer 中由 [index * 3]、[index * 3 + 1]、[index * 3 + 2] 表示的三角形。

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

XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT 结构的定义如下：

typedef struct XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT {
    XrStructureType        type;
    void*                  next;
    uint32_t               meshSemanticLabelsCount;
    XrSpatialBufferEXT*    meshSemanticLabels;
} XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT;

成员说明

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

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

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

有效用法（隐式）

配置

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中针对某项功能进行了枚举，则应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含该枚举来启用该功能。此组件不需要任何特殊配置即可包含在 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一个链中。不过，我们建议应用将此组件及其数据与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 组件结合使用。此组件不能与 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 一起启用。如果应用同时将 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 添加到 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。如果应用尝试在单独的 XrSpatialContextEXT 中同时启用这两个组件，则运行时必须返回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。

新结构

新枚举

新枚举常量

  • XR_EXT_SPATIAL_MESH_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_mesh_tracking_SPEC_VERSION

  • 扩展 XrSpatialCapabilityEXT：

    • XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

  • 扩展 XrSpatialCapabilityFeatureEXT：

    • XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

  • 扩展 XrSpatialComponentTypeEXT：

    • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT
    • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT
    • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

  • 扩展 XrStructureType：

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_MESH_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_NORMALS_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_TRIANGLE_SEMANTIC_LABELS_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_VERTEX_SEMANTIC_LABELS_LIST_EXT
    • XR_TYPE_SPATIAL_FEATURE_TRACK_WATERTIGHT_MESH_EXT

问题

版本历史记录

  • 修订版 1，2025-11-02（Nihav Jain，Google）

    • 初始扩展程序说明