XR_ANDROID_trackables_marker

名称字符串

XR_ANDROID_trackables_marker

扩展程序类型

实例扩展程序

已注册的扩展程序编号

708

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

XR_ANDROID_trackables

弃用状态

• 已弃用，取而代之的是 XR_EXT_spatial_marker_tracking 扩展程序

上次修改日期

2025-07-23

IP 状态

没有已知的 IP 权利主张。

创作贡献者

Christopher Doer，Google
Diego Tipaldi，Google
Levana Chen，Google
Jared Finder，Google
Spencer Quin，Google
Nihav Jain，Google
Ken Mackay，Google
Daniel Guttenberg，Qualcomm

概览

此扩展程序支持物理标记跟踪，并让应用能够以高效的方式将 XR 内容附加到物理标记。

该扩展程序支持知名的标记类型，特别是 ArUco 和 April 标记。它让运行时能够选择性地支持标记大小估计。

权限

Android 应用必须 在清单中列出 android.permission.SCENE_UNDERSTANDING_COARSE 权限，因为此扩展程序依赖于 XR_ANDROID_trackables 并会暴露环境的几何信息。android.permission.SCENE_UNDERSTANDING_COARSE 权限被视为危险权限，也就是说，应用必须 明确请求该权限。

（保护级别：危险）

检查系统功能

XrSystemMarkerTrackingPropertiesANDROID 结构的定义如下：

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

成员说明

• type 是此结构的 XrStructureType。
• next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。如需详细了解结构链，请参阅要扩展的结构 ( XrSystemProperties )。
• supportsMarkerTracking 是一个 XrBool32，用于指示当前系统是否提供标记跟踪功能。
• supportsMarkerSizeEstimation 是一个 XrBool32，用于指示当前系统是否提供标记大小估计。
• maxMarkerCount 是运行时能够同时跟踪的最大标记数量。

应用可以 在调用 xrGetSystemProperties 时，通过使用 XrSystemMarkerTrackingPropertiesANDROID 结构扩展 XrSystemProperties 来检查系统是否能够进行标记跟踪。当且仅当 supportsMarkerTracking 为 XR_FALSE 时，运行时必须 为标记跟踪器创建返回 XR_ERROR_FEATURE_UNSUPPORTED。

如果运行时支持标记跟踪，则 maxMarkerCount 必须 至少为 1。

有效用法（隐式）

• 必须先启用 XR_ANDROID_trackables_marker 扩展程序，然后才能使用 XrSystemMarkerTrackingPropertiesANDROID
• type 必须 为 XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
• next 必须 为 NULL 或指向结构链中下一个结构的有效指针

跟踪标记

此扩展程序会将 XR_TRACKABLE_TYPE_MARKER_ANDROID 添加到 XrTrackableTypeANDROID。

应用通过调用 xrCreateTrackableTrackerANDROID 并指定 XR_TRACKABLE_TYPE_MARKER_ANDROID 作为 XrTrackableTrackerCreateInfoANDROID :: trackableType 中的可跟踪对象类型来创建 XrTrackableTrackerANDROID，并通过将 XrTrackableMarkerConfigurationANDROID 添加到 XrTrackableTrackerCreateInfoANDROID 的下一个链来设置有效配置。

如果 XrTrackableTrackerCreateInfoANDROID :: trackableType 为 XR_TRACKABLE_TYPE_MARKER_ANDROID 且 XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking 通过 xrGetSystemProperties 返回 XR_FALSE，则运行时 必须 返回 XR_ERROR_FEATURE_UNSUPPORTED。

XrTrackableMarkerConfigurationANDROID 结构的定义如下：

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

成员说明

• type 是此结构的 XrStructureType。
• next 是 NULL 或指向结构链中下一个结构的指针。
• trackingMode 是一个 XrTrackableMarkerTrackingModeANDROID，用于指示所需的跟踪模式。
• databaseCount 是一个 uint32_t，用于描述 databases 数组中的元素数量。
• databases 是指向 XrTrackableMarkerDatabaseANDROID 数组的指针，每个数组都包含要跟踪的给定字典中的所需标记。

应用必须通过在调用xrCreateTrackableTrackerANDROID时将XrTrackableMarkerConfigurationANDROID添加到XrTrackableTrackerCreateInfoANDROID :: next链，并将XrTrackableTrackerCreateInfoANDROID :: trackableType设置为XR_TRACKABLE_TYPE_MARKER_ANDROID来设置有效配置。否则，如果跟踪器类型按上述方式设置，但配置结构不存在或无效，则运行时必须 返回 XR_ERROR_VALIDATION_FAILURE。

如果运行时支持标记大小估计，则应用可以 在 XrTrackableMarkerDatabaseANDROID :: entries 中将 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize 设置为 0，以指示使用大小估计。否则，应用必须 将 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize 设置为正值，否则运行时必须 返回 XR_ERROR_VALIDATION_FAILURE。

运行时必须 过滤 xrGetAllTrackablesANDROID 的输出，以匹配 trackingMode 和 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize。

有效用法（隐式）

• 必须先启用 XR_ANDROID_trackables_marker 扩展程序，然后才能使用 XrTrackableMarkerConfigurationANDROID
• type 必须 为 XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID
• next 必须 为 NULL 或指向结构链中下一个结构的有效指针
• trackingMode 必须 是有效的 XrTrackableMarkerTrackingModeANDROID 值
• databases 必须 是指向包含 databaseCount 个有效 XrTrackableMarkerDatabaseANDROID 结构的数组的指针
• databaseCount 参数 必须 大于 0

XrTrackableMarkerTrackingModeANDROID 枚举描述了标记支持的跟踪模式。

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

枚举值说明

• XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID - 跟踪动态标记。此模式的准确度最高，适用于移动和静态标记，但功耗也最高。
• XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID - 跟踪静态标记。此模式主要适用于已知为静态的标记，与动态模式相比，功耗更低。

XrTrackableMarkerDatabaseANDROID 结构定义了要跟踪的字典和相应标记 ID。

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

成员说明

• dictionary 是所有 entries 所属的 XrTrackableMarkerDictionaryANDROID。
• entryCount 是一个 uint32_t，用于描述 entries 数组中的元素数量。应用可以 将 entryCount 设置为 0，以跟踪 dictionary 中的所有标记。
• entries 是指向 XrTrackableMarkerDatabaseEntryANDROID 数组的指针，每个数组都包含要跟踪的标记的配置。

有效用法（隐式）

• 必须先启用 XR_ANDROID_trackables_marker 扩展程序，然后才能使用 XrTrackableMarkerDatabaseANDROID
• dictionary 必须 是有效的 XrTrackableMarkerDictionaryANDROID 值
• 如果 entryCount 不为 0，则 entries 必须 是指向包含 entryCount 个 XrTrackableMarkerDatabaseEntryANDROID 结构的数组的指针

XrTrackableMarkerDictionaryANDROID 枚举描述了支持的标记字典。

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

XrTrackableMarkerDatabaseEntryANDROID 结构配置了字典的单个标记 ID。

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

成员说明

• id 是字典中给定的标记 ID。
• edgeSize 表示标记边缘的大小（以米为单位）。如果运行时支持标记大小估计，则应用可以 将此值设置为零，系统将在线估计标记大小。如果此值设置为零，但运行时不支持标记大小估计，则运行时必须 返回 XR_ERROR_VALIDATION_FAILURE。

有效用法（隐式）

• 必须先启用 XR_ANDROID_trackables_marker 扩展程序，然后才能使用 XrTrackableMarkerDatabaseEntryANDROID

获取标记

xrGetTrackableMarkerANDROID 函数的定义如下：

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

参数说明

• tracker 是要查询的 XrTrackableTrackerANDROID。
• getInfo 是 XrTrackableGetInfoANDROID，其中包含了用于获取可跟踪标记的信息。
• markerOutput 是指向 XrTrackableMarkerANDROID 结构的指针，可跟踪标记将通过该结构返回。

如果 XrTrackableANDROID 的可跟踪对象类型不是 XR_TRACKABLE_TYPE_MARKER_ANDROID，或者 XrTrackableTrackerANDROID 的可跟踪对象类型不是 XR_TRACKABLE_TYPE_MARKER_ANDROID，则运行时 必须 返回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。

有效用法（隐式）

• 必须先启用 XR_ANDROID_trackables_marker 扩展程序，然后才能调用 xrGetTrackableMarkerANDROID
• tracker 必须 是有效的 XrTrackableTrackerANDROID 句柄
• getInfo 必须 是指向有效 XrTrackableGetInfoANDROID 结构的指针
• markerOutput 必须 是指向 XrTrackableMarkerANDROID 结构的指针

返回代码

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失败

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

XrTrackableMarkerANDROID 结构的定义如下：

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

成员说明

• type 是此结构的 XrStructureType。
• next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
• trackingState 是标记的 XrTrackingStateANDROID。
• lastUpdatedTime 是标记最后一次更新的 XrTime。
• dictionary 是标记的 XrTrackableMarkerDictionaryANDROID。
• markerId 是字典中给定的标记 ID。
• centerPose 是位于 XrTrackableGetInfoANDROID :: baseSpace 中的标记的 XrPosef。标记位于 XZ 平面中，X 指向标记的右侧，Z 指向标记的底部，Y 作为法线从标记中伸出。
• extents 是标记的 XrExtent2Df 尺寸。边界框的边界位于以下点：centerPose +/- ( extents / 2)。

有效用法（隐式）

• 必须先启用 XR_ANDROID_trackables_marker 扩展程序，然后才能使用 XrTrackableMarkerANDROID
• type 必须 为 XR_TYPE_TRACKABLE_MARKER_ANDROID
• next 必须 为 NULL 或指向结构链中下一个结构的有效指针
• trackingState 必须 是有效的 XrTrackingStateANDROID 值
• dictionary 必须 是有效的 XrTrackableMarkerDictionaryANDROID 值

获取可跟踪标记的示例代码

以下示例代码演示了如何获取可跟踪标记。

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

新增命令

• xrGetTrackableMarkerANDROID

新增结构

• XrTrackableMarkerANDROID
• XrTrackableMarkerDatabaseANDROID
• XrTrackableMarkerDatabaseEntryANDROID

• 扩展 XrSystemProperties：

  • XrSystemMarkerTrackingPropertiesANDROID

• 扩展 XrTrackableTrackerCreateInfoANDROID：

  • XrTrackableMarkerConfigurationANDROID

新增枚举

• XrTrackableMarkerDictionaryANDROID
• XrTrackableMarkerTrackingModeANDROID

新增枚举常量

• XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
• XR_ANDROID_trackables_marker_SPEC_VERSION

• 扩展 XrStructureType：

  • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_MARKER_ANDROID
  • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

• 扩展 XrTrackableTypeANDROID：

  • XR_TRACKABLE_TYPE_MARKER_ANDROID

问题

版本历史记录

• 修订版本 1，2025 年 7 月 23 日 (Levana Chen)

  • 初始扩展程序说明。