XR_ANDROID_trackables_qr_code

名稱字串

XR_ANDROID_trackables_qr_code

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

709

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_ANDROID_trackables

淘汰狀態

  • 已淘汰 XR_EXT_spatial_marker_tracking 擴充功能

上次修改日期

2025-02-05

IP 狀態

沒有已知的智慧財產權聲明。

著作人

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

總覽

這個擴充功能可追蹤實體 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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • supportsQrCodeTrackingXrBool32,表示目前系統是否提供 QR code 追蹤功能。
  • supportsQrCodeSizeEstimationXrBool32,指出目前系統是否提供 QR code 大小估算值。
  • maxQrCodeCount 是可同時追蹤的 QR code 總數上限。

應用程式可以在呼叫 xrGetSystemProperties 時,使用 XrSystemQrCodeTrackingPropertiesANDROID 結構體擴充 XrSystemProperties,檢查系統是否支援 QR code 追蹤功能。如果  是 ,則執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED,才能建立 QR code 追蹤程式。supportsQrCodeTrackingXR_FALSE

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

有效使用 (隱含)

  • XR_ANDROID_trackables_qr_code 擴充功能必須先啟用,才能使用 XrSystemQrCodeTrackingPropertiesANDROID
  • type 必須XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標

追蹤 QR code

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

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

如果 XrTrackableTrackerCreateInfoANDROID :: trackableTypeXR_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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • trackingModeXrQrCodeTrackingModeANDROID,表示追蹤的所需模式。
  • qrCodeEdgeSize 表示 QR code 邊緣的大小 (以公尺為單位)。如果為零,執行階段會線上估算 QR code 大小。

應用程式必須透過將 XrTrackableQrCodeConfigurationANDROID 新增至下一個 XrTrackableTrackerCreateInfoANDROID 鏈結,設定有效設定。否則,執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE

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

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

執行階段必須篩選 xrGetAllTrackablesANDROID 的輸出內容,以符合 trackingMode。如果 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize 未設為 ,則執行階段必須只傳回符合這個大小的 QR code。0.0如果 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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • trackingState 是 QR code 的 XrTrackingStateANDROID
  • lastUpdatedTime 是 QR code 上次更新的 XrTime。如果 lastUpdatedTime 與上次呼叫不同,所有其他欄位可能都會變更。
  • centerPose 是位於 XrTrackableGetInfoANDROID :: baseSpace 中的 QR code 的 XrPosef。QR code 位於 XZ 平面,其中 X 指向 QR code 的右側,Z 指向底部,Y 則從 QR code 伸出,做為法線。
  • extents 是 QR code 的 XrExtent2Df 維度。定界框的邊界位於點:centerPose +/- ( extents / 2)。
  • bufferCapacityInputbuffer0 擷取必要功能的容量。
  • bufferCountOutput 如果 bufferCapacityInput0,執行階段會將所需緩衝區空間大小寫入 bufferCountOutput。否則,其中會包含寫入 buffer 的元素總數。如果 QR code 資料尚未解碼,執行階段必須將 bufferCountOutput 設為 0。
  • bufferchar 陣列的指標,用於寫入解碼的 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 年 2 月 5 日 (Levana Chen)

    • 擴充功能說明。