名稱字串
XR_ANDROID_trackables_qr_code
擴充功能類型
延長執行個體期限
已註冊的分機號碼
460
修訂
1
擴充功能和版本依附元件
上次修改日期
2025-02-05
IP 狀態
未發現任何智慧財產權聲明。
著作人
Google 員工 Christopher Doer
Google 產品經理 Levana Chen
Google 員工 Jared Finder
Google 員工 Spencer Quin
Google 的 Nihav Jain
Google Diego Tipaldi
Google 肯麥凱
Daniel Guttenberg，Qualcomm
總覽
這個擴充功能可追蹤實體 QR code，並解碼 QR code 資料。
檢查系統功能
XrSystemQrCodeTrackingPropertiesANDROID
XrSystemQrCodeTrackingPropertiesANDROID 結構的定義如下：
typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsQrCodeTracking;
XrBool32 supportsQrCodeSizeEstimation;
uint32_t maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;
成員說明
type是這個結構的XrStructureType。next是NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。supportsQrCodeTracking是XrBool32，表示目前系統是否提供 QR code 追蹤功能。supportsQrCodeSizeEstimation是XrBool32，指出目前系統是否提供 QR Code 大小估算值。maxQrCodeCount是可同時追蹤的 QR Code 總數上限。
應用程式可以透過在呼叫 xrGetSystemProperties 時，使用 XrSystemQrCodeTrackingPropertiesANDROID 結構體擴充 XrSystemProperties，檢查系統是否支援 QR code 追蹤功能。如果 supportsQrCodeTracking 為 XR_FALSE，則執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED，才能建立 QR code 追蹤器。
如果執行階段支援 QR Code 追蹤，則必須隨時支援追蹤的 QR Code。maxQrCodeCount
如果執行階段支援 QR Code 大小預估功能，應用程式可以將 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 設為表示使用大小預估功能。否則，應用程式必須將 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 設為正值，否則系統會傳回 XR_ERROR_VALIDATION_FAILURE。
有效用量 (隱含)
- 使用
XrSystemQrCodeTrackingPropertiesANDROID前必須啟用XR_ANDROID_trackables_qr_code擴充功能 type必須為XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROIDnext必須是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
XrTrackableQrCodeConfigurationANDROID 結構的定義如下：
typedef struct XrTrackableQrCodeConfigurationANDROID {
XrStructureType type;
const 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，表示使用大小估算。否則，應用程式必須將 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 設為正值，否則系統會傳回 XR_ERROR_VALIDATION_FAILURE。
執行階段必須篩選 xrGetAllTrackablesANDROID 的輸出內容，以符合 trackingMode 和 qrCodeEdgeSize。
有效用量 (隱含)
- 使用
XrTrackableQrCodeConfigurationANDROID前必須啟用XR_ANDROID_trackables_qr_code擴充功能 type必須為XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROIDnext必須是NULL，或是結構體鏈結中下一個結構體的有效指標trackingMode必須是有效的XrQrCodeTrackingModeANDROID值
XrQrCodeTrackingModeANDROID
XrQrCodeTrackingModeANDROID 列舉會說明 QR Code 支援的追蹤模式。
typedef enum XrQrCodeTrackingModeANDROID {
XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 0,
XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;
| 列舉 | 說明 XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID'
| XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | QR code 為動態，可能會移動。 |
取得 QR code
xrGetTrackableQrCodeANDROID
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擴充功能必須啟用 tracker必須是有效的XrTrackableTrackerANDROID帳號代碼getInfo必須是指向有效XrTrackableGetInfoANDROID結構體的指標qrCodeOutput必須是指向XrTrackableQrCodeANDROID結構體的指標
XrTrackableQrCodeANDROID
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。centerPose是位於XrTrackableGetInfoANDROID::baseSpace的 QR CodeXrPosef。QR code 位於 XZ 平面，其中 X 指向 QR code 的右側，Z 指向底部。extents是 QR code 的XrExtent2Df維度。 定界框的邊界位於點：centerPose+/- (extents/ 2)。bufferCapacityInput是buffer或0擷取必要功能的容量。bufferCountOutput如果bufferCapacityInput為0，執行階段會將所需緩衝區大小寫入bufferCountOutput。否則會包含buffer中寫入的元素總數。buffer是指向char陣列的指標，用於寫入解碼的 QR code 資料。應用程式可以傳遞nullptr，判斷所需的緩衝區大小，或是否要求解碼 QR Code 資料。QR Code 資料會以空值終止的 UTF-8 字串形式傳回。- 如要詳細瞭解如何擷取必要的
buffer大小，請參閱「緩衝區大小參數」一節。
有效用量 (隱含)
- 使用
XrTrackableQrCodeANDROID前必須啟用XR_ANDROID_trackables_qr_code擴充功能 type必須為XR_TYPE_TRACKABLE_QR_CODE_ANDROIDnext必須是NULL，或是結構體鏈結中下一個結構體的有效指標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);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
qrCodes[i].next = nullptr;
qrCodes[i].bufferCountOutput = 0;
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));
新的列舉常數
XrStructureType 列舉會擴充為：
XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_QR_CODE_ANDROID
XrTrackableTypeANDROID 列舉會擴充為：
XR_TRACKABLE_TYPE_QR_CODE_ANDROID
新列舉
XrQrCodeTrackingModeANDROID
新結構
XrSystemQrCodeTrackingPropertiesANDROIDXrTrackableQrCodeConfigurationANDROIDXrTrackableQrCodeANDROID
新函式
xrGetTrackableQrCodeANDROID
問題
版本記錄
- 修訂版本 1，2025-02-05 (Levana Chen)
- 擴充功能的初始說明。
OpenXR™ 和 OpenXR 標誌是 The Khronos Group Inc. 的商標，已在中國、歐盟、日本和英國註冊為商標。