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。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。supportsQrCodeTracking是XrBool32,表示目前系統是否提供 QR code 追蹤功能。supportsQrCodeSizeEstimation是XrBool32,指出目前系統是否提供 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 :: 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 大小。
應用程式必須透過將 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 和估計大小。
有效使用 (隱含)
-
XR_ANDROID_trackables_qr_code擴充功能必須先啟用,才能使用 XrTrackableQrCodeConfigurationANDROID -
type必須為XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID -
nextmust 為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。
有效使用 (隱含)
- 呼叫 xrGetTrackableQrCodeANDROID 前,
XR_ANDROID_trackables_qr_code擴充功能必須啟用 -
trackermust 為有效的 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是位於 XrTrackableGetInfoANDROID ::baseSpace中的 QR code 的 XrPosef。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 -
nextmust 為NULL,或指向結構體鏈結中下一個結構體的有效指標。另請參閱:XrTrackableQrCodeVersionQCOM -
trackingState必須是有效的 XrTrackingStateANDROID 值 - 如果
bufferCapacityInput不是0,buffer必須是指向bufferCapacityInputchar 值陣列的指標
取得可追蹤 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 年 2 月 5 日 (Levana Chen)
- 擴充功能說明。