XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

709

リビジョン

1

Ratification Status（批准ステータス）

未批准

拡張機能とバージョンの依存関係

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 権限は危険な権限と見なされます。

（保護レベル: 危険）

システムの機能を検証する

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

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

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

• XR_ANDROID_trackables_qr_code 拡張機能は、XrSystemQrCodeTrackingPropertiesANDROID を使用する前に有効にしなければなりません。
• 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 構造体は次のように定義されます。

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

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

• xrGetTrackableQrCodeANDROID を呼び出す前に、XR_ANDROID_trackables_qr_code 拡張機能を有効にする必要があります。
• 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 サイズの取得について詳しくは、バッファ サイズ パラメータのセクションをご覧ください。

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

• XR_ANDROID_trackables_qr_code 拡張機能は、XrTrackableQrCodeANDROID を使用する前に有効にしなければなりません
• 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）

  • 拡張機能の初回説明。