XR_ANDROID_scene_meshing

名称字符串

XR_ANDROID_scene_meshing

扩展类型

实例扩展程序

已注册的扩展程序编号

719

修订版本

3

批准状态

未获批准

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2025-05-15

IP 状态

没有已知的 IP 权利主张。

创作贡献者

Spencer Quin,Google
Jared Finder,Google
Antonio Fontan,Google
Cairn Overturf,Google
Nihav Jain,Google
Salar Khan,Google
Sebastian Klose,Google
Jürgen Sturm,Google
Vinny DaSilva,Google
Ricardo Campbell,Google

概览

此扩展程序旨在提供大致表示用户环境中物理对象的网格。

应用可以使用此扩展程序来直观呈现场景,并让虚拟对象与物理对象(例如碰撞)互动。

场景网格数据由运行时生成,并使用 XrSceneMeshingTrackerANDROIDXrSceneMeshSnapshotANDROID 与应用共享。应用可以通过从 xrGetAllSubmeshStatesANDROID 返回的 XrSceneSubmeshStateANDROID 访问场景子网格信息中的值。应用可以通过从 xrGetSubmeshDataANDROID 返回的 XrSceneSubmeshDataANDROID 访问场景子网格数据中的值。

场景网格化数据属于敏感的个人信息,与个人隐私和完整性密切相关。强烈建议存储或传输场景网格化数据的应用始终要求用户主动明确接受才能执行此操作。

权限

Android 应用必须在其清单中列出 android.permission.SCENE_UNDERSTANDING_FINE 权限。android.permission.SCENE_UNDERSTANDING_FINE 权限被视为敏感权限,因为它允许运行时研究用户环境。

应用必须在运行时请求该权限才能使用以下函数:

(保护级别:危险)

检查系统功能

XrSystemSceneMeshingPropertiesANDROID 结构的定义如下:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

成员说明

  • type 是相应结构的 XrStructureType
  • nextNULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • supportsSceneMeshing 是一个 XrBool32,用于指示系统是否支持场景网格化。

应用可以通过在调用 xrGetSystemProperties 时将 XrSystemSceneMeshingPropertiesANDROID 结构体链接到 XrSystemProperties 来检查系统是否支持场景网格化。

如果运行时针对 supportsSceneMeshing 返回 XR_FALSE,则表示系统不支持场景网格化,因此必须xrCreateSceneMeshingTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。当 supportsSceneMeshingXR_FALSE 时,应用避免使用场景网格化功能。

如果某个运行时针对 supportsSceneMeshing 返回 XR_TRUE,则表示系统支持场景网格化。

有效使用情况(隐式)

XrSceneMeshSemanticLabelSetANDROID 枚举描述了场景网格划分的语义标签集。此枚举中的每个值都表示包含语义标签的另一个枚举。例如,值 XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID 表示集合 XrSceneMeshSemanticLabelANDROID

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

枚举值具有以下含义:

枚举说明

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

此语义标签集表示没有语义标签。

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

此语义标签集表示 XrSceneMeshSemanticLabelANDROID。

xrEnumerateSupportedSemanticLabelSetsANDROID 函数的定义如下:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

参数说明

  • instance 是由应用创建的 XrInstance
  • systemId 是从 xrGetSystem 重试的 XrSystemId
  • supportedSemanticLabelSetsInputCapacitysupportedSemanticLabelSets 的容量,或设为 0 以检索所需的容量。
  • supportedSemanticLabelSetsOutputCount 是一个指针,指向写入的 supportedSemanticLabelSets 数量;若 supportedSemanticLabelSetsInputCapacity 容量不足,则指向所需的容量。
  • supportedSemanticLabelSets 是指向 XrSceneMeshSemanticLabelSetANDROID 数组的指针。如果 supportedSemanticLabelSetsInputCapacity 为 0,它可以NULL
  • 如需详细了解如何检索所需的 supportedSemanticLabelSets 大小,请参阅缓冲区大小参数一章。

应用可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函数枚举系统支持的语义标签集。

每个系统必须至少支持 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,因为此枚举值表示没有语义标签集,并且可以在应用不需要顶点语义的情况下使用。

有效使用情况(隐式)

  • 必须先启用 XR_ANDROID_scene_meshing 扩展程序,然后才能调用 xrEnumerateSupportedSemanticLabelSetsANDROID
  • instance 必须是有效的 XrInstance 句柄
  • supportedSemanticLabelSetsOutputCount 必须是指向 uint32_t 值的指针
  • 如果 supportedSemanticLabelSetsInputCapacity 不为 0 ,则 supportedSemanticLabelSets 必须是指向包含 supportedSemanticLabelSetsInputCapacityXrSceneMeshSemanticLabelSetANDROID 值的数组的指针

返回代码

成功

  • 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

创建场景网格化跟踪器句柄

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

XrSceneMeshingTrackerANDROID 句柄表示用于场景网格化和管理相关资源的场景网格化跟踪器。

此句柄用于在此扩展程序中使用 xrCreateSceneMeshSnapshotANDROID 创建场景网格快照。

xrCreateSceneMeshingTrackerANDROID 函数的定义如下:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

参数说明

应用可以使用 xrCreateSceneMeshingTrackerANDROID 函数创建 XrSceneMeshingTrackerANDROID 句柄。

如果系统不支持场景网格化,运行时必须xrCreateSceneMeshingTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。在这种情况下,当调用 xrGetSystemProperties 函数时,运行时必须针对 XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing 返回 XR_FALSE,以便应用可以避免创建场景网格化跟踪器。

应用在创建场景网格化跟踪器时,必须仅使用 XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet 中受系统支持的语义标签集。如果应用使用的场景网格顶点语义标签集不受支持,运行时必须xrCreateSceneMeshingTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED

应用可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函数来枚举受支持的语义标签集列表。

xrCreateSceneMeshingTrackerANDROID 句柄拥有场景网格化的所有资源。完成场景网格化体验后,应用必须通过 xrDestroySceneMeshingTrackerANDROID 函数销毁句柄。

有效使用情况(隐式)

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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_VALIDATION_FAILURE

XrSceneMeshingTrackerCreateInfoANDROID 结构的定义如下:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

成员说明

  • type 是相应结构的 XrStructureType
  • nextNULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • semanticLabelSet 是一个 XrSceneMeshSemanticLabelSetANDROID,用于指定要用于场景网格化的语义标签集。如果此标志设置为 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,运行时将忽略 XrSceneSubmeshDataANDROID :: vertexSemantics 缓冲区字段。
  • enableNormals 是一种 XrBool32,用于指定在获取场景网格数据时是否在场景网格缓冲区中包含网格顶点的顶点法线。

XrSceneMeshingTrackerCreateInfoANDROID 结构描述了用于创建 XrSceneMeshingTrackerANDROID 句柄的信息。

有效使用情况(隐式)

xrDestroySceneMeshingTrackerANDROID 函数的定义如下:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

参数说明

xrDestroySceneMeshingTrackerANDROID 函数会在完成场景网格化体验后释放 tracker 和底层资源。

有效使用情况(隐式)

线程安全

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

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

创建场景网格快照句柄

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

XrSceneMeshSnapshotANDROID 句柄表示场景网格快照。此快照是使用 xrCreateSceneMeshSnapshotANDROID 创建的,该函数会在调用时拍摄场景网格数据的快照。

此句柄可以用于通过 xrGetAllSubmeshStatesANDROIDxrGetSubmeshDataANDROID 检索子网格信息和数据。

xrCreateSceneMeshSnapshotANDROID 函数的定义如下:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

参数说明

应用可以使用 xrCreateSceneMeshSnapshotANDROID 函数从场景网格化跟踪器创建场景网格快照。此函数会返回一个 XrSceneMeshSnapshotANDROID 句柄,以及封装在 XrSceneMeshSnapshotCreationResultANDROID 结构中的 XrSceneMeshTrackingStateANDROID。从技术上讲,句柄是创建时场景网格数据的快照。此句柄可以分别用于使用 xrGetAllSubmeshStatesANDROIDxrGetSubmeshDataANDROID 查询场景网格信息和数据。

有效使用情况(隐式)

返回代码

成功

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

XrSceneMeshSnapshotCreateInfoANDROID 结构的定义如下:

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

成员说明

  • type 是相应结构的 XrStructureType
  • nextNULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • baseSpace 是表示场景子网格姿态信息的 XrSpace
  • time 是描述场景网格将被处理或显示的时间的 XrTime,通常为 XrFrameState :: predictedDisplayTime
  • boundingBox 是一个 XrBoxf,用于描述获取场景网格的边界框。

XrSceneMeshSnapshotCreateInfoANDROID 结构描述了用于创建 XrSceneMeshSnapshotANDROID 句柄的信息

有效使用情况(隐式)

XrSceneMeshSnapshotCreationResultANDROID 结构的定义如下:

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

会员说明

  • type 是相应结构的 XrStructureType
  • nextNULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • snapshot 是由运行时创建的 XrSceneMeshSnapshotANDROID 句柄。
  • trackingState 是一个 XrSceneMeshTrackingStateANDROID,用于描述创建快照时场景网格化跟踪器的状态。

XrSceneMeshSnapshotCreationResultANDROID 结构用于存储通过 xrCreateSceneMeshSnapshotANDROID 返回的场景网格快照创建结果。

有效使用情况(隐式)

XrSceneMeshTrackingStateANDROID 枚举描述了场景网格化跟踪器的跟踪状态。此枚举中的每个值都代表场景网格化跟踪器的状态。

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

枚举值具有以下含义:

枚举说明

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

追踪器尚未准备好提供网格数据。

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

跟踪器正在主动跟踪。

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

自上次网格更新以来,跟踪器一直在等待有效的测量结果以进行整合。

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

该跟踪器在多个周期内未收到有效衡量数据,处于错误状态。

此状态仅作为应用的附加信息。在没有其他错误源的情况下,无论跟踪器的当前 XrSceneMeshTrackingStateANDROID 如何,运行时必须继续允许应用创建快照并从中检索数据。如果状态不是 XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID,则快照可能不是最新状态或为空。

从场景网格快照获取场景网格数据

xrGetAllSubmeshStatesANDROID 函数的定义如下:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

参数说明

  • snapshot 是一个先前使用 xrCreateSceneMeshSnapshotANDROID 创建的 XrSceneMeshSnapshotANDROID 句柄。
  • submeshStateCapacityInputsubmeshStates 的容量,或设为 0 以检索所需的容量。
  • submeshStateCountOutput 是一个指针,指向写入的 submeshStates 数量;若 submeshStateCapacityInput 容量不足,则指向所需的容量。
  • submeshStates 是一个指向 XrSceneSubmeshStateANDROID 结构数组的指针,运行时会将场景网格中所有子网格的状态输出到该数组。如果 submeshStateCapacityInput 为 0,它可以NULL
  • 如需详细了解如何检索所需的 submeshStates 大小,请参阅缓冲区大小参数一章。

应用可以使用 xrGetAllSubmeshStatesANDROID 函数来获取场景网格中所有子网格的状态。此对象包含基本信息,可让应用选择应用需要哪些子网格的数据。

有效使用情况(隐式)

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

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

XrSceneSubmeshStateANDROID 结构的定义如下:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

成员说明

  • type 是相应结构的 XrStructureType
  • nextNULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • submeshId 是用于标识子网格的 XrUuid
  • lastUpdatedTime 是一个 XrTime,表示子网格上次更新的时间。
  • submeshPoseInBaseSpace 是一个 XrPosef,表示用于创建场景网格快照的基础空间中子网格的姿势。姿势也是子网格边界框的中心。
  • bounds 是一个 XrExtent3Df,用于描述封装子网格的边界框的尺寸。此边界是在用于创建场景网格句柄的基础空间中定义的。

运行时会尽最大努力将 submeshId 与子网格所占用的物理空间区域进行映射。运行时可能随时丢失此映射,并为检测到的任何子网格子集分配新的 UUID。特别是,运行时无需在后续应用实例中为同一网格重复使用相同的 UUID。

有效使用情况(隐式)

xrGetSubmeshDataANDROID 函数的定义如下:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

参数说明

应用可以使用 xrGetSubmeshDataANDROID 函数,通过传递 XrSceneSubmeshDataANDROID 的列表来获取一批子网格或所有子网格,其中每个 XrSceneSubmeshDataANDROID :: submeshId 都设置为要检索的子网格的相应 ID。

XrSceneSubmeshDataANDROID :: submeshId 必须对于 inoutSubmeshData 中的每个元素都是唯一的,并且可通过 xrGetAllSubmeshStatesANDROID 为同一 snapshot 进行检索。如果子网格 ID 无效,或者 inoutSubmeshData 中的多个元素具有相同的子网格 ID,则运行时必须返回 XR_ERROR_VALIDATION_FAILURE

submeshDataCount 必须小于或等于 xrGetAllSubmeshStatesANDROID 返回的值 :: submeshStateCountOutput,否则运行时必须返回 XR_ERROR_VALIDATION_FAILURE

此函数可以在 2 调用惯用语中使用,以查询所有选定子网格的顶点和索引数量。

有效使用情况(隐式)

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

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

XrSceneSubmeshDataANDROID 结构的定义如下:

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

成员说明

  • type 是相应结构的 XrStructureType
  • nextNULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • submeshId 是用于标识子网格的 XrUuid
  • vertexCapacityInputvertexPositionsvertexNormalsvertexSemantics 的容量,或设为 0 以检索所需的容量。
  • vertexCountOutput 是一个指针,指向写入的 vertexPositionsvertexNormalsvertexSemantics 数量;若 vertexCapacityInput 容量不足,则指向所需的容量。
  • vertexPositions 是一个 XrVector3f 数组,运行时会将子网格的顶点位置输出到该数组。
  • vertexNormals 是一个 XrVector3f 数组,运行时会将子网格的顶点法线输出到该数组。如果应用创建的跟踪器的正常状态处于停用状态,则此字段可以留空 (NULL)。
  • vertexSemantics 是一个 uint8_t 数组,运行时会将子网格的顶点语义输出到该数组。如果应用创建的跟踪器的语义标签设置为 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,则此字段可以留空 (NULL)。
  • indexCapacityInputindices 的容量,或设为 0 以检索所需的容量。
  • indexCountOutput 是一个指针,指向写入的 indices 数量;若 vertexCapacityInput 容量不足,则指向所需的容量。
  • indices 是一个 uint32_t 数组,运行时会将子网格的索引输出到该数组。
  • 如需详细了解如何检索所需的 vertexPositionsvertexNormalsvertexSemanticsindices 大小,请参阅缓冲区大小参数一章。

有效使用情况(隐式)

  • XR_ANDROID_scene_meshing 扩展程序必须先启用,然后才能使用 XrSceneSubmeshDataANDROID
  • type 必须XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next 必须NULL 或指向结构链中下一个结构的有效指针
  • 如果 vertexCapacityInput 不为 0,则 vertexPositions 必须是指向 vertexCapacityInputXrVector3f 结构体数组的指针
  • 如果 vertexCapacityInput 不为 0,则 vertexNormals 必须是指向 vertexCapacityInputXrVector3f 结构体数组的指针
  • 如果 vertexCapacityInput 不是 0,则 vertexSemantics 必须是指向 vertexCapacityInputuint8_t 值的数组的指针
  • 如果 indexCapacityInput 不是 0,则 indices 必须是指向 indexCapacityInputuint32_t 值的数组的指针

XrSceneMeshSemanticLabelANDROID 枚举是一组默认的语义标签,用于标记网格顶点,以描述网格顶点所在的物理环境表面。此枚举集由 XrSceneMeshSemanticLabelSetANDROID 中的 XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID 值表示。

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

枚举具有以下含义:

枚举说明

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

此语义标签表示对应的网格元素代表一个未知对象。

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

此语义标签表示对应的网格元素代表地面。

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

此语义标签表示对应的网格元素代表天花板。

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

此语义标签表示对应的网格元素代表墙壁。

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

此语义标签表示对应的网格元素代表一个表格。

销毁场景网格快照

xrDestroySceneMeshSnapshotANDROID 函数的定义如下:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

参数说明

应用可以使用 xrDestroySceneMeshSnapshotANDROID 函数来销毁场景网格快照。销毁句柄后,应用无法再使用该句柄获取子网格信息或数据。当跟踪器被销毁时,句柄会自动销毁,因为跟踪器句柄是场景网格快照句柄的父级。

有效使用情况(隐式)

线程安全

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

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

场景网格化示例代码

以下示例代码演示了如何访问场景网格数据以进行渲染。

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

新的对象类型

新增命令

新结构

新枚举

新的枚举常量

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION
  • 扩展 XrObjectType

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID
  • 扩展 XrStructureType

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

问题

版本历史记录

  • 修订版 3,2025-05-15(Salar Khan)

    • 初始扩展程序说明