Name String
XR_ANDROID_trackables_qr_code
拡張機能のタイプ
インスタンス拡張機能
Registered Extension Number
460
リビジョン
1
拡張機能とバージョンの依存関係
最終更新日
2025-02-05
IP ステータス
既知の IP 申し立てはありません。
寄与者
Christopher Doer（Google）
Levana Chen（Google）
Jared Finder, Google
Spencer Quin（Google）
Nihav Jain、Google
Diego Tipaldi（Google）
Google の Ken Mackay
Daniel Guttenberg、Qualcomm
概要
この拡張機能により、物理的な QR コードのトラッキングと QR コードのデータのデコードが可能になります。
システムの機能を検証する
XrSystemQrCodeTrackingPropertiesANDROID
XrSystemQrCodeTrackingPropertiesANDROID 構造体は次のように定義されます。
typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsQrCodeTracking;
XrBool32 supportsQrCodeSizeEstimation;
uint32_t maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;
メンバーの説明
typeは、この構造のXrStructureTypeです。nextは、NULLまたは構造体チェーン内の次の構造体へのポインタです。このような構造は、コア OpenXR またはこの拡張機能では定義されていません。supportsQrCodeTrackingは、現在のシステムが QR コード トラッキング機能を提供しているかどうかを示すXrBool32です。supportsQrCodeSizeEstimationは、現在のシステムが QR コードのサイズ推定を提供するかどうかを示すXrBool32です。maxQrCodeCountは、同時に追跡できる QR コードの合計最大数です。
アプリは、xrGetSystemProperties を呼び出すときに XrSystemProperties を XrSystemQrCodeTrackingPropertiesANDROID 構造体で拡張することで、システムが QR コードのトラッキングに対応しているかどうかを確認できます。ランタイムは、supportsQrCodeTracking が XR_FALSE の場合にのみ、QR コード トラッカーの作成に対して XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。
ランタイムが QR コード トラッキングをサポートする場合、任意の時点で maxQrCodeCount 個のトラッキング対象 QR コードをサポートしなければなりません。
ランタイムが QR コードのサイズ推定をサポートしている場合、アプリは XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 を設定して、サイズ推定の使用を示すことができます。それ以外の場合、アプリケーションは XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize を正の値に設定しなければなりません。そうしないと、XR_ERROR_VALIDATION_FAILURE が返されます。
有効な使用方法（暗黙的）
XrSystemQrCodeTrackingPropertiesANDROIDを使用する前に、XR_ANDROID_trackables_qr_code拡張機能を有効にする必要があります。typeはXR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROIDでなければなりません。nextは、NULLまたは構造体チェーン内の次の構造体への有効なポインタでなければなりません。
QR コードのトラッキング
この拡張機能は、XrTrackableTypeANDROID に XR_TRACKABLE_TYPE_QR_CODE_ANDROID を追加します。
アプリケーションは、xrCreateTrackableTrackerANDROID を呼び出し、XrTrackableTrackerCreateInfoANDROID::trackableType の追跡可能なタイプとして XR_TRACKABLE_TYPE_QR_CODE_ANDROID を指定して、QR コードを追跡することにより、XrTrackableTrackerANDROID を作成しても構いません。
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 コードの辺の長さをメートル単位で示します。0 の場合、QR コードのサイズはオンラインで推定されます。
アプリケーションは、XrTrackableTrackerCreateInfoANDROID の次のチェーンに XrTrackableQrCodeConfigurationANDROID を追加して、有効な構成を設定しなければなりません。それ以外の場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。
ランタイムが QR コードのサイズ推定をサポートしている場合、アプリは 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_ANDROIDでなければなりません。nextは、NULLまたは構造体チェーン内の次の構造体への有効なポインタでなければなりません。trackingModeは有効なXrQrCodeTrackingModeANDROID値でなければなりません。
XrQrCodeTrackingModeANDROID
XrQrCodeTrackingModeANDROID 列挙型は、QR コードのサポートされているトラッキング モードを表します。
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 コードは動的で、移動する可能性があります。 |
QR コードを取得する
xrGetTrackableQrCodeANDROID
xrGetTrackableQrCodeANDROID 関数は次のように定義されます。
XrResult xrGetTrackableQrCodeANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableQrCodeANDROID* qrCodeOutput);
パラメータの説明
trackerは、クエリするXrTrackableTrackerANDROIDです。getInfoは、追跡可能な QR コードを取得するために使用される情報を含むXrTrackableGetInfoANDROIDです。qrCodeOutputは、追跡可能な QR コードが返されるXrTrackableQrCodeANDROID構造体へのポインタです。
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 コードのXrTrackingStateANDROIDです。lastUpdatedTimeは、QR コードの最終更新のXrTimeです。centerPoseは、XrTrackableGetInfoANDROID::baseSpaceにある QR コードのXrPosefです。QR コードは XZ 平面にあり、X は QR コードの右を指し、Z は QR コードの下を指します。extentsは QR コードのXrExtent2Dfディメンションです。境界ボックスの境界は、centerPose+/-（extents/ 2）のポイントにあります。bufferCapacityInputは、必要な機能をbufferまたは0で取得する機能です。bufferCountOutputbufferCapacityInputが0の場合、ランタイムは必要なバッファサイズをbufferCountOutputに書き込みます。それ以外の場合は、bufferに書き込まれた要素の合計が含まれます。bufferは、デコードされた QR コードデータを書き込むcharの配列へのポインタです。アプリケーションは、必要なバッファサイズを決定するため、または QR コードデータのデコードをリクエストしない場合に、nullptrを渡すことができます。QR コードデータは、null 終端の UTF-8 文字列として返されます。- 必要な
bufferサイズの取得について詳しくは、バッファサイズ パラメータのセクションをご覧ください。
有効な使用方法（暗黙的）
XrTrackableQrCodeANDROIDを使用する前に、XR_ANDROID_trackables_qr_code拡張機能を有効にする必要があります。typeはXR_TYPE_TRACKABLE_QR_CODE_ANDROIDでなければなりません。nextは、NULLまたは構造体チェーン内の次の構造体への有効なポインタでなければなりません。trackingStateは有効なXrTrackingStateANDROID値でなければなりません。bufferCapacityInputが0でない場合、bufferはbufferCapacityInputchar 値の配列へのポインタでなければなりません。
追跡可能な QR コードを取得するサンプルコード
次のサンプルコードは、追跡可能な QR コードを取得する方法を示しています。
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 年 2 月 5 日（Levana Chen）
- 拡張機能の初期の説明。
OpenXR™ および OpenXR のロゴは、Khronos Group Inc. が所有する商標であり、中国、欧州連合、日本、英国で商標として登録されています。