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 ステータス

既知の 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 コードのトラッキングと QR コードデータのデコードが可能になります。

権限

この拡張機能は XR_ANDROID_trackables に依存し、環境のジオメトリを公開するため、Android アプリのマニフェストに android.permission.SCENE_UNDERSTANDING_COARSE 権限を記載する必要があります。android.permission.SCENE_UNDERSTANDING_COARSE 権限は、危険な権限と見なされます。

（保護レベル: dangerous）

システム機能を検査する

XrSystemQrCodeTrackingPropertiesANDROID 構造体は次のように定義されます。

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• supportsQrCodeTracking は、現在のシステムが QR コード トラッキング機能を提供しているかどうかを示す XrBool32 です。
• supportsQrCodeSizeEstimation は、現在のシステムが QR コードのサイズ推定を提供するかどうかを示す XrBool32 です。
• maxQrCodeCount は、同時にトラッキングできる QR コードの合計最大数です。

アプリケーションは、xrGetSystemProperties を呼び出すときに、XrSystemQrCodeTrackingPropertiesANDROID 構造体を使用して XrSystemProperties を拡張することで、システムが QR コード トラッキングに対応しているかどうかを検査できます。ランタイムは、supportsQrCodeTracking が XR_FALSE の場合に限り、QR コード トラッカーの作成に対して XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

ランタイムが QR コード トラッキングをサポートしている場合、maxQrCodeCount は 1 以上でなければなりません。ランタイムが QR コードのトラッキングをサポートしていない場合、maxQrCodeCount は 0 でなければなりません。

有効な使用方法（暗黙的）

• 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 を指定することで、XrTrackableTrackerANDROID を作成しても構いません。

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 コードの端のサイズをメートル単位で表します。0 の場合、ランタイムは QR コードのサイズをオンラインで推定します。

アプリは、XrTrackableTrackerCreateInfoANDROID の次のチェーンに XrTrackableQrCodeConfigurationANDROID を追加して、有効な構成を設定しなければなりません。それ以外の場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムが QR コードのサイズ推定をサポートしている場合、アプリケーションは XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize を 0.0 に設定して、サイズ推定の使用を示すことができます。

ランタイムが QR コードのサイズ推定をサポートしていない場合、アプリは XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize を正の値に設定しなければなりません。そうしない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返しなければなりません。

ランタイムは、trackingMode と一致するように xrGetAllTrackablesANDROID からの出力をフィルタしなければなりません。XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize が 0.0 に設定されていない場合、ランタイムは、このサイズに一致する QR コードのみを返さなければなりません。XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize が 0.0 に設定されている場合、ランタイムは推定サイズを持つすべての QR コードを返さなければなりません。

有効な使用方法（暗黙的）

• XrTrackableQrCodeConfigurationANDROID を使用する前に、XR_ANDROID_trackables_qr_code 拡張機能を有効にする必要があります。
• type は XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタである必要があります。XrTrackableQrCodeVersionFilterQCOM もご覧ください。
• trackingMode は、有効な XrQrCodeTrackingModeANDROID 値でなければなりません。

XrQrCodeTrackingModeANDROID 列挙型は、サポートされている QR コードのトラッキング モードを記述します。

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 コードのトラッキング。このモードは精度が最も高く、移動する QR コードと静的な QR コードの両方に対応しますが、消費電力も最も高くなります。
• XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID - 静的 QR コードのトラッキング。このモードは、主に静的であることがわかっている QR コードに役立ちます。動的モードと比較して消費電力が少なくなります。
• XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM - このモードは、静的な QR コードに使用します。静的モードとは異なり、このモードでは QR コードを 1 回だけ追跡し、その後はデバイスの位置のみに基づいて追跡されたインスタンスの位置を更新します。その結果、QR コードが基準フレームの視野から外れても、トラッキングは継続されます。これにより、QR コードがトラッキングされた後の消費電力を最小限に抑えることができます。（XR_QCOM_trackables_qr_code_operations 拡張機能によって追加）

QR コードを取得する

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 を返さなければなりません。

有効な使用方法（暗黙的）

• XR_ANDROID_trackables_qr_code 拡張機能は、xrGetTrackableQrCodeANDROID を呼び出す前に有効にする必要があります。
• tracker は、有効な XrTrackableTrackerANDROID ハンドルでなければなりません。
• getInfo は、有効な XrTrackableGetInfoANDROID 構造体へのポインタでなければなりません。
• qrCodeOutput は、XrTrackableQrCodeANDROID 構造体へのポインタでなければなりません。

戻りコード

成功

• 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 です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• trackingState は、QR コードの XrTrackingStateANDROID です。
• lastUpdatedTime は、QR コードの最終更新の XrTime です。lastUpdatedTime が最後の呼び出しから変更されている場合、他のすべてのフィールドが変更されている可能性があります。
• centerPose は、XrTrackableGetInfoANDROID :: baseSpace にある QR コードの XrPosef です。QR コードは XZ 平面にあり、X は QR コードの右側を指し、Z は QR コードの下部を指し、Y は QR コードから法線として出ています。
• extents は、QR コードの XrExtent2Df ディメンションです。境界ボックスの境界は、centerPose +/-（extents / 2）のポイントにあります。
• bufferCapacityInput は buffer の機能、または必要な機能を取得する 0 です。
• bufferCountOutput bufferCapacityInput が 0 の場合、ランタイムは必要なバッファサイズを bufferCountOutput に書き込みます。それ以外の場合は、buffer に書き込まれた要素の合計が含まれます。QR コードデータがまだデコードされていない場合、ランタイムは bufferCountOutput を 0 に設定しなければなりません。
• buffer は、デコードされた QR コードデータを書き込む char の配列へのポインタです。アプリケーションがデコードされた QR コードデータを必要としない場合は、nullptr を渡して 2 回目の呼び出しを省略できます。QR コードデータは、null で終わる UTF-8 文字列として返されます。
• 必要な buffer サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

有効な使用方法（暗黙的）

• XrTrackableQrCodeANDROID を使用する前に、XR_ANDROID_trackables_qr_code 拡張機能を有効にする必要があります。
• type は XR_TYPE_TRACKABLE_QR_CODE_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタである必要があります。XrTrackableQrCodeVersionQCOM もご覧ください。
• trackingState は、有効な XrTrackingStateANDROID 値でなければなりません。
• bufferCapacityInput が 0 でない場合、buffer は bufferCapacityInput の char 値の配列へのポインタでなければなりません。

トラッキング可能な 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, {
  .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));

新しいコマンド

• xrGetTrackableQrCodeANDROID

新しい構造

• XrTrackableQrCodeANDROID

• XrSystemProperties の拡張:

  • XrSystemQrCodeTrackingPropertiesANDROID

• XrTrackableTrackerCreateInfoANDROID の拡張:

  • XrTrackableQrCodeConfigurationANDROID

新しい列挙型

• XrQrCodeTrackingModeANDROID

新しい列挙型定数

• 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-02-05（Levana Chen）

  • 拡張機能の初期説明。