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。
有效用途 (隱含)
- 必須先啟用
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。
應用程式可以建立 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 及其預估大小。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_qr_code擴充功能,才能使用 XrTrackableQrCodeConfigurationANDROID -
type「必須」為XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標。另請參閱:XrTrackableQrCodeVersionFilterQCOM -
trackingMode「必須」為有效的 XrQrCodeTrackingModeANDROID 值
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);
參數說明
tracker是要查詢的 XrTrackableTrackerANDROID。getInfo是 XrTrackableGetInfoANDROID,其中包含用於取得可追蹤 QR code 的資訊。qrCodeOutput是 XrTrackableQrCodeANDROID 結構的指標,可追蹤的 QR code 會傳回至該結構。
如果 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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_TIME_INVALIDXR_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大小,請參閱「緩衝區大小參數」一節。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_qr_code擴充功能,才能使用 XrTrackableQrCodeANDROID -
type「必須」為XR_TYPE_TRACKABLE_QR_CODE_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標。另請參閱:XrTrackableQrCodeVersionQCOM -
trackingState「必須」是有效的 XrTrackingStateANDROID 值 - 如果
bufferCapacityInput不是0,buffer「必須」是指向bufferCapacityInput個字元值陣列的指標
取得可追蹤 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_NAMEXR_ANDROID_trackables_qr_code_SPEC_VERSION擴充 XrStructureType:
XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_QR_CODE_ANDROIDXR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
-
XR_TRACKABLE_TYPE_QR_CODE_ANDROID
問題
版本記錄
修訂版本 1,2025-02-05 (Levana Chen)
- 初始擴充功能說明。