XR_ANDROID_scene_meshing
名称字符串
XR_ANDROID_scene_meshing
扩展类型
实例扩展程序
已注册的扩展程序编号
719
修订版本
3
批准状态
未获批准
扩展程序和版本依赖项
上次修改日期
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
概览
此扩展程序旨在提供大致表示用户环境中物理对象的网格。
应用可以使用此扩展程序来直观呈现场景,并让虚拟对象与物理对象(例如碰撞)互动。
场景网格数据由运行时生成,并使用 XrSceneMeshingTrackerANDROID 和 XrSceneMeshSnapshotANDROID 与应用共享。应用可以通过从 xrGetAllSubmeshStatesANDROID 返回的 XrSceneSubmeshStateANDROID 访问场景子网格信息中的值。应用可以通过从 xrGetSubmeshDataANDROID 返回的 XrSceneSubmeshDataANDROID 访问场景子网格数据中的值。
场景网格化数据属于敏感的个人信息,与个人隐私和完整性密切相关。强烈建议存储或传输场景网格化数据的应用始终要求用户主动明确接受才能执行此操作。
权限
Android 应用必须在其清单中列出 android.permission.SCENE_UNDERSTANDING_FINE 权限。android.permission.SCENE_UNDERSTANDING_FINE 权限被视为敏感权限,因为它允许运行时研究用户环境。
应用必须在运行时请求该权限才能使用以下函数:
- xrCreateSceneMeshingTrackerANDROID
- xrDestroySceneMeshingTrackerANDROID
- xrCreateSceneMeshSnapshotANDROID
- xrDestroySceneMeshSnapshotANDROID
- xrGetAllSubmeshStatesANDROID
- xrGetSubmeshDataANDROID
(保护级别:危险)
检查系统功能
XrSystemSceneMeshingPropertiesANDROID 结构的定义如下:
typedef struct XrSystemSceneMeshingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;
成员说明
type是相应结构的 XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。supportsSceneMeshing是一个XrBool32,用于指示系统是否支持场景网格化。
应用可以通过在调用 xrGetSystemProperties 时将 XrSystemSceneMeshingPropertiesANDROID 结构体链接到 XrSystemProperties 来检查系统是否支持场景网格化。
如果运行时针对 supportsSceneMeshing 返回 XR_FALSE,则表示系统不支持场景网格化,因此必须从 xrCreateSceneMeshingTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。当 supportsSceneMeshing 为 XR_FALSE 时,应用应避免使用场景网格化功能。
如果某个运行时针对 supportsSceneMeshing 返回 XR_TRUE,则表示系统支持场景网格化。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能使用 XrSystemSceneMeshingPropertiesANDROID -
type必须为XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针
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。supportedSemanticLabelSetsInputCapacity是supportedSemanticLabelSets的容量,或设为 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必须是指向包含supportedSemanticLabelSetsInputCapacity个 XrSceneMeshSemanticLabelSetANDROID 值的数组的指针
返回代码
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
创建场景网格化跟踪器句柄
XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)
XrSceneMeshingTrackerANDROID 句柄表示用于场景网格化和管理相关资源的场景网格化跟踪器。
此句柄可用于在此扩展程序中使用 xrCreateSceneMeshSnapshotANDROID 创建场景网格快照。
xrCreateSceneMeshingTrackerANDROID 函数的定义如下:
XrResult xrCreateSceneMeshingTrackerANDROID(
XrSession session,
const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
XrSceneMeshingTrackerANDROID* tracker);
参数说明
session是场景网格化跟踪器将处于活动状态的 XrSession。createInfo是一个指向 XrSceneMeshingTrackerCreateInfoANDROID 结构的指针,用于描述要创建的场景网格化跟踪器。tracker是返回的 XrSceneMeshingTrackerANDROID 句柄。
应用可以使用 xrCreateSceneMeshingTrackerANDROID 函数创建 XrSceneMeshingTrackerANDROID 句柄。
如果系统不支持场景网格化,运行时必须从 xrCreateSceneMeshingTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。在这种情况下,当调用 xrGetSystemProperties 函数时,运行时必须针对 XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing 返回 XR_FALSE,以便应用可以避免创建场景网格化跟踪器。
应用在创建场景网格化跟踪器时,必须仅使用 XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet 中受系统支持的语义标签集。如果应用使用的场景网格顶点语义标签集不受支持,运行时必须从 xrCreateSceneMeshingTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。
应用可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函数来枚举受支持的语义标签集列表。
xrCreateSceneMeshingTrackerANDROID 句柄拥有场景网格化的所有资源。完成场景网格化体验后,应用必须通过 xrDestroySceneMeshingTrackerANDROID 函数销毁句柄。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能调用 xrCreateSceneMeshingTrackerANDROID -
session必须是有效的 XrSession 句柄 -
createInfo必须是指向有效 XrSceneMeshingTrackerCreateInfoANDROID 结构的指针 -
tracker必须是指向 XrSceneMeshingTrackerANDROID 句柄的指针
返回代码
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
XrSceneMeshingTrackerCreateInfoANDROID 结构的定义如下:
typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSceneMeshSemanticLabelSetANDROID semanticLabelSet;
XrBool32 enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;
成员说明
type是相应结构的 XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。semanticLabelSet是一个 XrSceneMeshSemanticLabelSetANDROID,用于指定要用于场景网格化的语义标签集。如果此标志设置为XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,运行时将忽略 XrSceneSubmeshDataANDROID ::vertexSemantics缓冲区字段。enableNormals是一种XrBool32,用于指定在获取场景网格数据时是否在场景网格缓冲区中包含网格顶点的顶点法线。
XrSceneMeshingTrackerCreateInfoANDROID 结构描述了用于创建 XrSceneMeshingTrackerANDROID 句柄的信息。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能使用 XrSceneMeshingTrackerCreateInfoANDROID -
type必须为XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针 -
semanticLabelSet必须是有效的 XrSceneMeshSemanticLabelSetANDROID 值
xrDestroySceneMeshingTrackerANDROID 函数的定义如下:
XrResult xrDestroySceneMeshingTrackerANDROID(
XrSceneMeshingTrackerANDROID tracker);
参数说明
tracker是一个先前由 xrCreateSceneMeshingTrackerANDROID 创建的 XrSceneMeshingTrackerANDROID。
xrDestroySceneMeshingTrackerANDROID 函数会在完成场景网格化体验后释放 tracker 和底层资源。
有效使用情况(隐式)
-
XR_ANDROID_scene_meshing扩展程序必须先启用,然后才能调用 xrDestroySceneMeshingTrackerANDROID -
tracker必须是有效的 XrSceneMeshingTrackerANDROID 句柄
线程安全
- 对
tracker及其任何子句柄的访问都必须在外部进行同步
返回代码
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
创建场景网格快照句柄
XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)
XrSceneMeshSnapshotANDROID 句柄表示场景网格快照。此快照是使用 xrCreateSceneMeshSnapshotANDROID 创建的,该函数会在调用时拍摄场景网格数据的快照。
此句柄可以用于通过 xrGetAllSubmeshStatesANDROID 和 xrGetSubmeshDataANDROID 检索子网格信息和数据。
xrCreateSceneMeshSnapshotANDROID 函数的定义如下:
XrResult xrCreateSceneMeshSnapshotANDROID(
XrSceneMeshingTrackerANDROID tracker,
const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
XrSceneMeshSnapshotCreationResultANDROID* outSnapshotCreationResult);
参数说明
tracker是一个先前使用 xrCreateSceneMeshingTrackerANDROID 创建的 XrSceneMeshingTrackerANDROID 句柄。createInfo是一个指向 XrSceneMeshSnapshotCreateInfoANDROID 结构的指针,其中包含创建场景网格快照所需的必要信息。outSnapshotCreationResult是一个指向 XrSceneMeshSnapshotCreationResultANDROID 对象的指针,该对象由运行时填充快照创建结果。
应用可以使用 xrCreateSceneMeshSnapshotANDROID 函数从场景网格化跟踪器创建场景网格快照。此函数会返回一个 XrSceneMeshSnapshotANDROID 句柄,以及封装在 XrSceneMeshSnapshotCreationResultANDROID 结构中的 XrSceneMeshTrackingStateANDROID。从技术上讲,句柄是创建时场景网格数据的快照。此句柄可以分别用于使用 xrGetAllSubmeshStatesANDROID 和 xrGetSubmeshDataANDROID 查询场景网格信息和数据。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能调用 xrCreateSceneMeshSnapshotANDROID -
tracker必须是有效的 XrSceneMeshingTrackerANDROID 句柄 -
createInfo必须是指向有效 XrSceneMeshSnapshotCreateInfoANDROID 结构的指针 -
outSnapshotCreationResult必须是指向 XrSceneMeshSnapshotCreationResultANDROID 结构的指针
返回代码
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALID
XrSceneMeshSnapshotCreateInfoANDROID 结构的定义如下:
typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpace baseSpace;
XrTime time;
XrBoxf boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;
成员说明
type是相应结构的 XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。baseSpace是表示场景子网格姿态信息的 XrSpace。time是描述场景网格将被处理或显示的时间的XrTime,通常为 XrFrameState ::predictedDisplayTime。boundingBox是一个 XrBoxf,用于描述获取场景网格的边界框。
XrSceneMeshSnapshotCreateInfoANDROID 结构描述了用于创建 XrSceneMeshSnapshotANDROID 句柄的信息
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能使用 XrSceneMeshSnapshotCreateInfoANDROID -
type必须为XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针 -
baseSpace必须是有效的 XrSpace 句柄
XrSceneMeshSnapshotCreationResultANDROID 结构的定义如下:
typedef struct XrSceneMeshSnapshotCreationResultANDROID {
XrStructureType type;
const void* next;
XrSceneMeshSnapshotANDROID snapshot;
XrSceneMeshTrackingStateANDROID trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;
会员说明
type是相应结构的 XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。snapshot是由运行时创建的 XrSceneMeshSnapshotANDROID 句柄。trackingState是一个 XrSceneMeshTrackingStateANDROID,用于描述创建快照时场景网格化跟踪器的状态。
XrSceneMeshSnapshotCreationResultANDROID 结构用于存储通过 xrCreateSceneMeshSnapshotANDROID 返回的场景网格快照创建结果。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能使用 XrSceneMeshSnapshotCreationResultANDROID -
type必须为XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针 -
snapshot必须是有效的 XrSceneMeshSnapshotANDROID 句柄 -
trackingState必须是有效的 XrSceneMeshTrackingStateANDROID 值
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 句柄。submeshStateCapacityInput是submeshStates的容量,或设为 0 以检索所需的容量。submeshStateCountOutput是一个指针,指向写入的submeshStates数量;若submeshStateCapacityInput容量不足,则指向所需的容量。submeshStates是一个指向 XrSceneSubmeshStateANDROID 结构数组的指针,运行时会将场景网格中所有子网格的状态输出到该数组。如果submeshStateCapacityInput为 0,它可以为NULL。- 如需详细了解如何检索所需的
submeshStates大小,请参阅缓冲区大小参数一章。
应用可以使用 xrGetAllSubmeshStatesANDROID 函数来获取场景网格中所有子网格的状态。此对象包含基本信息,可让应用选择应用需要哪些子网格的数据。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能调用 xrGetAllSubmeshStatesANDROID -
snapshot必须是有效的 XrSceneMeshSnapshotANDROID 句柄 -
submeshStateCountOutput必须是指向uint32_t值的指针 - 如果
submeshStateCapacityInput不为0,则submeshStates必须是指向submeshStateCapacityInput个 XrSceneSubmeshStateANDROID 结构体数组的指针
返回代码
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_VALIDATION_FAILURE
XrSceneSubmeshStateANDROID 结构的定义如下:
typedef struct XrSceneSubmeshStateANDROID {
XrStructureType type;
void* next;
XrUuid submeshId;
XrTime lastUpdatedTime;
XrPosef submeshPoseInBaseSpace;
XrExtent3Df bounds;
} XrSceneSubmeshStateANDROID;
成员说明
type是相应结构的 XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。submeshId是用于标识子网格的 XrUuid。lastUpdatedTime是一个XrTime,表示子网格上次更新的时间。submeshPoseInBaseSpace是一个 XrPosef,表示用于创建场景网格快照的基础空间中子网格的姿势。姿势也是子网格边界框的中心。bounds是一个 XrExtent3Df,用于描述封装子网格的边界框的尺寸。此边界是在用于创建场景网格句柄的基础空间中定义的。
运行时会尽最大努力将 submeshId 与子网格所占用的物理空间区域进行映射。运行时可能随时丢失此映射,并为检测到的任何子网格子集分配新的 UUID。特别是,运行时无需在后续应用实例中为同一网格重复使用相同的 UUID。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_scene_meshing扩展程序,然后才能使用 XrSceneSubmeshStateANDROID -
type必须为XR_TYPE_SCENE_SUBMESH_STATE_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针
xrGetSubmeshDataANDROID 函数的定义如下:
XrResult xrGetSubmeshDataANDROID(
XrSceneMeshSnapshotANDROID snapshot,
uint32_t submeshDataCount,
XrSceneSubmeshDataANDROID* inoutSubmeshData);
参数说明
snapshot是一个先前使用 xrCreateSceneMeshSnapshotANDROID 创建的 XrSceneMeshSnapshotANDROID 句柄。submeshDataCount是inoutSubmeshData的长度。inoutSubmeshData是一个应用分配的 XrSceneSubmeshDataANDROID 数组,运行时会在其中填充与 XrSceneSubmeshDataANDROID ::submeshId中传递的子网格 ID 关联的网格数据。
应用可以使用 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_ANDROID_scene_meshing扩展程序,然后才能调用 xrGetSubmeshDataANDROID -
snapshot必须是有效的 XrSceneMeshSnapshotANDROID 句柄 -
inoutSubmeshData必须是指向submeshDataCountXrSceneSubmeshDataANDROID 结构数组的指针 -
submeshDataCount参数必须大于0
返回代码
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_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。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。submeshId是用于标识子网格的 XrUuid。vertexCapacityInput是vertexPositions、vertexNormals和vertexSemantics的容量,或设为 0 以检索所需的容量。vertexCountOutput是一个指针,指向写入的vertexPositions、vertexNormals和vertexSemantics数量;若vertexCapacityInput容量不足,则指向所需的容量。vertexPositions是一个 XrVector3f 数组,运行时会将子网格的顶点位置输出到该数组。vertexNormals是一个 XrVector3f 数组,运行时会将子网格的顶点法线输出到该数组。如果应用创建的跟踪器的正常状态处于停用状态,则此字段可以留空 (NULL)。vertexSemantics是一个uint8_t数组,运行时会将子网格的顶点语义输出到该数组。如果应用创建的跟踪器的语义标签设置为XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,则此字段可以留空 (NULL)。indexCapacityInput是indices的容量,或设为 0 以检索所需的容量。indexCountOutput是一个指针,指向写入的indices数量;若vertexCapacityInput容量不足,则指向所需的容量。indices是一个uint32_t数组,运行时会将子网格的索引输出到该数组。- 如需详细了解如何检索所需的
vertexPositions、vertexNormals、vertexSemantics和indices大小,请参阅缓冲区大小参数一章。
有效使用情况(隐式)
-
XR_ANDROID_scene_meshing扩展程序必须先启用,然后才能使用 XrSceneSubmeshDataANDROID -
type必须为XR_TYPE_SCENE_SUBMESH_DATA_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针 - 如果
vertexCapacityInput不为0,则vertexPositions必须是指向vertexCapacityInput个 XrVector3f 结构体数组的指针 - 如果
vertexCapacityInput不为0,则vertexNormals必须是指向vertexCapacityInput个 XrVector3f 结构体数组的指针 - 如果
vertexCapacityInput不是0,则vertexSemantics必须是指向vertexCapacityInput个uint8_t值的数组的指针 - 如果
indexCapacityInput不是0,则indices必须是指向indexCapacityInput个uint32_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);
参数说明
snapshot是一个先前使用 xrCreateSceneMeshSnapshotANDROID 创建的 XrSceneMeshSnapshotANDROID 句柄,将由该函数销毁。
应用可以使用 xrDestroySceneMeshSnapshotANDROID 函数来销毁场景网格快照。销毁句柄后,应用无法再使用该句柄获取子网格信息或数据。当跟踪器被销毁时,句柄会自动销毁,因为跟踪器句柄是场景网格快照句柄的父级。
有效使用情况(隐式)
-
XR_ANDROID_scene_meshing扩展程序必须先启用,然后才能调用 xrDestroySceneMeshSnapshotANDROID -
snapshot必须是有效的 XrSceneMeshSnapshotANDROID 句柄
线程安全
- 对
snapshot及其任何子句柄的访问都必须在外部进行同步
返回代码
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_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));
新的对象类型
新增命令
- xrCreateSceneMeshSnapshotANDROID
- xrCreateSceneMeshingTrackerANDROID
- xrDestroySceneMeshSnapshotANDROID
- xrDestroySceneMeshingTrackerANDROID
- xrEnumerateSupportedSemanticLabelSetsANDROID
- xrGetAllSubmeshStatesANDROID
- xrGetSubmeshDataANDROID
新结构
- XrSceneMeshSnapshotCreateInfoANDROID
- XrSceneMeshSnapshotCreationResultANDROID
- XrSceneMeshingTrackerCreateInfoANDROID
- XrSceneSubmeshDataANDROID
- XrSceneSubmeshStateANDROID
新枚举
新的枚举常量
XR_ANDROID_SCENE_MESHING_EXTENSION_NAMEXR_ANDROID_scene_meshing_SPEC_VERSION扩展 XrObjectType:
XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROIDXR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID
扩展 XrStructureType:
XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROIDXR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROIDXR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROIDXR_TYPE_SCENE_SUBMESH_DATA_ANDROIDXR_TYPE_SCENE_SUBMESH_STATE_ANDROIDXR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
问题
版本历史记录
修订版 3,2025-05-15(Salar Khan)
- 初始扩展程序说明