XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

709

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_ANDROID_trackables

淘汰狀態

  • XR_EXT_spatial_marker_tracking 擴充功能已淘汰

上次修改日期

2025-02-05

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

總覽

這項擴充功能可追蹤實體 QR code 並解碼 QR code 資料。

權限

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,表示目前系統是否提供 QR code 追蹤功能。
  • supportsQrCodeSizeEstimation 是 XrBool32,表示目前系統是否提供 QR code 大小估算功能。
  • maxQrCodeCount 是可同時追蹤的 QR code 數量上限。

應用程式可以檢查系統是否能追蹤 QR code,方法是在呼叫 xrGetSystemProperties 時,使用 XrSystemQrCodeTrackingPropertiesANDROID 結構擴充 XrSystemProperties。只有在 supportsQrCodeTracking 為 XR_FALSE 時,執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED,才能建立 QR code 追蹤程式。

如果執行階段支援 QR code 追蹤,maxQrCodeCount 必須至少為 1。如果執行階段不支援 QR code 追蹤,maxQrCodeCount 必須為 0。

有效用途 (隱含)

追蹤 QR code

這項擴充功能會將 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 新增至 XrTrackableTypeANDROID。

應用程式可以建立 XrTrackableTrackerANDROID,方法是呼叫 xrCreateTrackableTrackerANDROID,並在 XrTrackableTrackerCreateInfoANDROID :: trackableType 中指定 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 做為可追蹤類型,以追蹤 QR code。

如果 XrTrackableTrackerCreateInfoANDROID :: trackableType 為 XR_TRACKABLE_TYPE_QR_CODE_ANDROID,且 XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking 透過 xrGetSystemProperties 傳回 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 表示 QR code 邊長 (以公尺為單位)。如果為零,執行階段會線上估算 QR code 大小。

應用程式必須設定有效設定,方法是在 XrTrackableTrackerCreateInfoANDROID 的下一個鏈結中,新增 XrTrackableQrCodeConfigurationANDROID。否則,執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果執行階段支援 QR code 大小估算,應用程式可能會將 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 設為 0.0,表示使用大小估算功能。

如果執行階段不支援 QR code 大小估算,應用程式必須將 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 設為正值,否則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

執行階段必須篩選 xrGetAllTrackablesANDROID 的輸出內容,以符合 trackingMode。如果 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 未設為 0.0,執行階段必須只傳回符合這個大小的 QR code。如果 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 設為 0.0,執行階段必須傳回所有 QR code 及其預估大小。

有效用途 (隱含)

XrQrCodeTrackingModeANDROID 列舉說明 QR code 支援的追蹤模式。

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:追蹤動態 QR code。這個模式的準確度最高,適用於動態和靜態 QR code,但耗電量也最高。
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID:追蹤靜態 QR code。這個模式主要適用於已知為靜態的 QR code,相較於動態模式,耗電量較低。
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM:這個模式適用於靜態 QR code。與靜態模式相反,這個模式只會追蹤 QR code 一次,然後僅根據裝置的位置更新追蹤例項的位置。因此,即使 QR code 移出參考影格的視野,追蹤仍會繼續。追蹤 QR code 後,耗電量會降到最低。(由 XR_QCOM_trackables_qr_code_operations 擴充功能新增)

取得 QR code

xrGetTrackableQrCodeANDROID 函式的定義如下:

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

參數說明

如果 XrTrackableANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_QR_CODE_ANDROID,或 XrTrackableTrackerANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_QR_CODE_ANDROID,執行階段必須傳回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。

有效用途 (隱含)

傳回代碼

成功

  • 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 是 QR code 的 XrTrackingStateANDROID。
  • lastUpdatedTime 是 QR code 上次更新的XrTime。如果 lastUpdatedTime 自上次呼叫後有所變更,所有其他欄位「可能」已變更。
  • centerPose 是 QR code 的 XrPosef,位於 XrTrackableGetInfoANDROID :: baseSpace。QR code 位於 XZ 平面,X 指向 QR code 右側,Z 指向底部,Y 則從 QR code 延伸出來,做為法線。
  • extents 是 QR code 的 XrExtent2Df 維度。定界框的邊界位於以下點:centerPose +/- ( extents / 2)。
  • bufferCapacityInput 是 buffer 的功能,或 0 擷取所需功能。
  • bufferCountOutput 如果 bufferCapacityInput 為 0,執行階段會將所需的緩衝區空間寫入 bufferCountOutput。否則,其中會包含 buffer 中寫入的元素總數。如果 QR code 資料尚未解碼,執行階段必須將 bufferCountOutput 設為 0。
  • buffer 是指向 char 陣列的指標,用於寫入解碼的 QR code 資料。如果應用程式不在意解碼的 QR code 資料,則可以傳遞 nullptr 並省略第二個呼叫。QR code 資料會以空值終止的 UTF-8 字串傳回。
  • 如要進一步瞭解如何擷取必要的 buffer 大小,請參閱「緩衝區大小參數」一節。

有效用途 (隱含)

取得可追蹤 QR code 的程式碼範例

下列程式碼範例說明如何取得可追蹤的 QR code。

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));

新指令

新結構

新列舉

新列舉常數

  • 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-02-05 (Levana Chen)

    • 初始擴充功能說明。