Android XR for OpenXR | Android Developers

Android XR SDK 已达到开发者预览版 4，我们希望收到您的反馈！您可以尝试一下，然后访问我们的支持页面与我们联系。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

XR_ANDROID_trackables_qr_code

名称字符串

XR_ANDROID_trackables_qr_code

扩展类型

实例扩展程序

已注册的扩展程序编号

709

修订版本

批准状态

未获批准

扩展程序和版本依赖项

XR_ANDROID_trackables

弃用状态

已被 XR_EXT_spatial_marker_tracking 扩展程序弃用

上次修改日期

2025-02-05

IP 状态

没有已知的 IP 权利主张。

创作贡献者

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

概览

此扩展程序可实现实体二维码跟踪和二维码数据解码。

权限

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

（保护级别：危险）

检查系统功能

XrSystemQrCodeTrackingPropertiesANDROID 结构的定义如下：

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

成员说明

type 是相应结构的 XrStructureType。
next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
supportsQrCodeTracking 是一个 XrBool32，用于指示当前系统是否提供二维码跟踪功能。
supportsQrCodeSizeEstimation 是一个 XrBool32，用于指示当前系统是否提供二维码大小估计。
maxQrCodeCount 是可同时跟踪的二维码总数上限。

应用可以通过在调用 xrGetSystemProperties 时使用 XrSystemQrCodeTrackingPropertiesANDROID 结构扩展 XrSystemProperties 来检查系统是否支持二维码跟踪。当且仅当 supportsQrCodeTracking 为 XR_FALSE 时，运行时必须针对二维码跟踪广告代码创建返回 XR_ERROR_FEATURE_UNSUPPORTED。

如果运行时支持二维码跟踪，则 maxQrCodeCount 必须至少为 1。如果某个运行时不支持二维码跟踪，则 maxQrCodeCount 必须为 0。

有效使用情况（隐式）

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

跟踪二维码

此扩展程序将 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 添加到 XrTrackableTypeANDROID。

应用可以通过调用 xrCreateTrackableTrackerANDROID 并在 XrTrackableTrackerCreateInfoANDROID :: trackableType 中指定 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 作为可跟踪对象类型来创建 XrTrackableTrackerANDROID，以跟踪二维码。

如果 XrTrackableTrackerCreateInfoANDROID :: trackableType 为 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 且 xrGetSystemProperties 返回的 XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking 为 XR_FALSE，则运行时必须返回 XR_ERROR_FEATURE_UNSUPPORTED。

XrTrackableQrCodeConfigurationANDROID 结构的定义如下：

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    XrQrCodeTrackingModeANDROID    trackingMode;
    float                          qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

成员说明

type 是相应结构的 XrStructureType。
next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
trackingMode 是一个 XrQrCodeTrackingModeANDROID，用于指示所需的跟踪模式。
qrCodeEdgeSize 表示二维码边缘的大小（以米为单位）。如果为零，则运行时会在线估计二维码大小。

应用必须通过将 XrTrackableQrCodeConfigurationANDROID 添加到 XrTrackableTrackerCreateInfoANDROID 的下一个链中来设置有效配置。否则，运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

如果运行时支持二维码大小估计，应用可以将 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 设置为 0.0，以指示使用大小估计。

如果运行时不支持二维码大小估计，应用必须将 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 设置为正值，否则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

运行时必须过滤 xrGetAllTrackablesANDROID 的输出，以匹配 trackingMode。如果 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 未设置为 0.0，则运行时必须仅返回与此大小匹配的二维码。如果 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 设置为 0.0，运行时必须返回所有具有估计大小的二维码。

有效使用情况（隐式）

XR_ANDROID_trackables_qr_code 扩展程序必须先启用，然后才能使用 XrTrackableQrCodeConfigurationANDROID
type 必须为 XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
next 必须是 NULL 或指向结构链中下一个结构的有效指针。另请参阅：XrTrackableQrCodeVersionFilterQCOM
trackingMode 必须是有效的 XrQrCodeTrackingModeANDROID 值

XrQrCodeTrackingModeANDROID 枚举描述了二维码支持的跟踪模式。

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM = 1000314000,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

枚举常量说明

XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID - 跟踪动态二维码。此模式具有最高的准确性，可识别移动和静态二维码，但功耗也最高。
XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID - 跟踪静态二维码。此模式主要适用于已知为静态的二维码，与动态模式相比，功耗更低。
XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM - 此模式应适用于静态二维码。与静态模式相反，此模式只会跟踪二维码一次，然后仅根据设备的位置更新跟踪实例的位置。因此，即使二维码不在参考帧的视野范围内，跟踪也会继续进行。这样一来，在跟踪到二维码后，功耗会降至最低。（由 XR_QCOM_trackables_qr_code_operations 扩展程序添加）

获取二维码

xrGetTrackableQrCodeANDROID 函数的定义如下：

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

参数说明

tracker 是要查询的 XrTrackableTrackerANDROID。
getInfo 是 XrTrackableGetInfoANDROID，其中包含了用于获取可跟踪二维码的信息。
qrCodeOutput 是一个指向 XrTrackableQrCodeANDROID 结构的指针，可跟踪的二维码将通过该结构返回。

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

有效使用情况（隐式）

XR_ANDROID_trackables_qr_code 扩展程序必须先启用，然后才能调用 xrGetTrackableQrCodeANDROID
tracker 必须是有效的 XrTrackableTrackerANDROID 句柄
getInfo 必须是指向有效 XrTrackableGetInfoANDROID 结构的指针
qrCodeOutput 必须是指向 XrTrackableQrCodeANDROID 结构的指针

返回代码

成功

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_SIZE_INSUFFICIENT
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

XrTrackableQrCodeANDROID 结构的定义如下：

typedef struct XrTrackableQrCodeANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrTime                    lastUpdatedTime;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    uint32_t                  bufferCapacityInput;
    uint32_t                  bufferCountOutput;
    char*                     buffer;
} XrTrackableQrCodeANDROID;

成员说明

type 是相应结构的 XrStructureType。
next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
trackingState 是二维码的 XrTrackingStateANDROID。
lastUpdatedTime 是二维码最后一次更新的 XrTime。如果 lastUpdatedTime 相较于上次调用发生了变化，则所有其他字段可能都发生了变化。
centerPose 是位于 XrTrackableGetInfoANDROID :: baseSpace 中的二维码的 XrPosef。二维码位于 XZ 平面内，其中 X 指向二维码的右侧，Z 指向二维码的底部，Y 指向二维码的外部作为法线。
extents 是二维码的 XrExtent2Df 尺寸。边界框的边界位于点：centerPose +/- ( extents / 2)。
bufferCapacityInput 是 buffer 的功能，或 0 用于检索所需的功能。
bufferCountOutput 如果 bufferCapacityInput 为 0，运行时会将所需的缓冲区空间写入 bufferCountOutput。否则，它包含在 buffer 中写入的总元素数。如果尚未对二维码数据进行解码，运行时必须将 bufferCountOutput 设置为 0。
buffer 是一个指向 char 数组的指针，用于写入解码后的二维码数据。如果应用不关心解码后的二维码数据，则可以传递 nullptr 并省略第二次双调用。QR 码数据以 null 终止的 UTF-8 字符串形式返回。
如需详细了解如何检索所需的 buffer 大小，请参阅缓冲区大小参数部分。

有效使用情况（隐式）

XR_ANDROID_trackables_qr_code 扩展程序必须先启用，然后才能使用 XrTrackableQrCodeANDROID
type 必须为 XR_TYPE_TRACKABLE_QR_CODE_ANDROID
next 必须是 NULL 或指向结构链中下一个结构的有效指针。另请参阅：XrTrackableQrCodeVersionQCOM
trackingState 必须是有效的 XrTrackingStateANDROID 值
如果 bufferCapacityInput 不为 0，则 buffer 必须是指向 bufferCapacityInput 个 char 值数组的指针

获取可跟踪二维码的示例代码

以下示例代码演示了如何获取可跟踪的二维码。

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_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID;           // 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
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty {
  .type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &qrCodeProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
    // QR code tracking is not supported.
    return;
}

// Create a trackable tracker for QR code tracking.
// If the runtime does not support size estimation, configures QR code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
  .qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID
};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get QR codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables.at(i),
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
    if (qrCodes[i].bufferCountOutput > 0) {
        // Allocate the buffer if it is not already allocated.
        if (qrCodes[i].bufferCapacityInput == 0) {
            qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
            qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
            CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
        }
    }
}

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

新增命令

xrGetTrackableQrCodeANDROID

新结构

XrTrackableQrCodeANDROID
扩展 XrSystemProperties：
- XrSystemQrCodeTrackingPropertiesANDROID
扩展 XrTrackableTrackerCreateInfoANDROID：
- XrTrackableQrCodeConfigurationANDROID

新枚举

XrQrCodeTrackingModeANDROID

新的枚举常量

XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
XR_ANDROID_trackables_qr_code_SPEC_VERSION
扩展 XrStructureType：
- XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
- XR_TYPE_TRACKABLE_QR_CODE_ANDROID
- XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
扩展 XrTrackableTypeANDROID：
- XR_TRACKABLE_TYPE_QR_CODE_ANDROID

问题

版本历史记录

修订版 1，2025 年 2 月 5 日（Levana Chen）
- 初始扩展程序说明。