XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

710

リビジョン

1

Ratification Status（批准ステータス）

未批准

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

XR_EXT_future
と
XR_ANDROID_trackables

最終更新日

2025-04-08

IP ステータス

既知の IP 申し立てはありません。

寄与者

Christopher Doer、Google
Levana Chen、Google
Jared Finder、Google
Spencer Quin、Google
Nihav Jain、Google
Diego Tipaldi、Google
Daniel Guttenberg、Qualcomm
Mark Vadasi、Qualcomm
Markus Birkner、Qualcomm
Maximilian Mayer、Qualcomm

概要

この拡張機能により、入力参照画像のセットで指定された平面画像をトラッキングできます。

権限

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

（保護レベル: 危険）

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

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。構造チェーンの詳細については、拡張される構造（XrSystemProperties）をご覧ください。
  • supportsImageTracking は、現在のシステムが画像トラッキング機能を提供するかどうかを示す XrBool32 です。
  • supportsPhysicalSizeEstimation は、現在のシステムが画像サイズの推定を提供するかどうかを示す XrBool32 です。
  • maxTrackedImageCount は、同時にトラッキングできる画像の合計最大数です。
  • maxLoadedImageCount は、すべてのデータベースで読み込むことができる参照画像の合計最大数です。

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

ランタイムが画像トラッキングをサポートする場合、任意の時点で maxTrackedImageCount 個のトラッキング対象画像をサポートしなければなりません。

ランタイムが画像トラッキングをサポートする場合、任意の時点で maxLoadedImageCount 個の読み込まれた画像をサポートしなければなりません。

ランタイムが画像サイズの推定をサポートしている場合、アプリケーションは XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 を設定して、サイズ推定の使用を示すことができます。それ以外の場合、アプリケーションは XrTrackableImageDatabaseEntryANDROID :: physicalWidth を正の値に設定しなければなりません。そうしないと、XR_ERROR_VALIDATION_FAILURE が返されます。

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

データベースの作成

アプリケーションは、1 つ以上の XrTrackableImageDatabaseEntryANDROID 構造体を作成し、XrTrackableImageDatabaseCreateInfoANDROID 構造体を介して xrCreateTrackableImageDatabaseAsyncANDROID 関数に渡すことで、XrTrackableImageDatabaseANDROID ハンドルを作成できます。

アプリケーションは、XrTrackableImageDatabaseANDROID ハンドルを作成する際に、少なくとも 1 つの XrTrackableImageDatabaseEntryANDROID を提供しなければなりません。

XrTrackableImageDatabaseANDROID は、環境内で検出および追跡できる処理済みの参照画像のセットを表すハンドルです。

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • trackingMode は、トラッキングの目的のモードを示す XrTrackableImageTrackingModeANDROID です。
  • physicalWidth は、画像の幅をメートル単位で示します。0 の場合、画像サイズはオンラインで推定されます。
  • imageWidth は、画像の幅をピクセル単位で示します。
  • imageHeight は、画像の高さをピクセル単位で示します。
  • format は、buffer の画像データの形式を示す XrTrackableImageFormatANDROID です。
  • bufferSize は、buffer のバイト長を示します。
  • buffer は、参照画像の画像ピクセルデータを含む uint8_t バッファです。buffer の内容は、xrCreateTrackableImageDatabaseAsyncANDROID によって開始され、xrCreateTrackableImageDatabaseCompleteANDROID によって完了するデータベース作成の非同期オペレーションの期間中、有効でなければなりません。

XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation が XR_TRUE の場合、アプリケーションは physicalWidth を 0 に設定して、オンライン サイズ推定をリクエストしても構いません。

エントリの imageWidth、imageHeight、format に基づく想定されるサイズと bufferSize が一致しない場合、ランタイムは xrCreateTrackableImageDatabaseAsyncANDROID から XR_ERROR_VALIDATION_FAILURE を返すことがあります。

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

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • entryCount は、entries 配列内の要素の数を指定する uint32_t です。
  • entries は XrTrackableImageDatabaseEntryANDROID 構造体の配列です。

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

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

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • futureResult は、非同期オペレーションの XrResult です。
  • database は、作成された XrTrackableImageDatabaseANDROID ハンドルです。

今後の返品コード

futureResult の値:

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

xrCreateTrackableImageDatabaseAsyncANDROID 関数は次のように定義されます。

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

パラメータの説明

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

xrCreateTrackableImageDatabaseCompleteANDROID 関数は次のように定義されます。

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

パラメータの説明

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

xrDestroyTrackableImageDatabaseANDROID 関数は次のように定義されます。

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

パラメータの説明

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

スレッドセーフ

  • database とその子ハンドルのアクセスは、外部で同期しなければなりません

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

トラッキング画像

この拡張機能により、XrTrackableTypeANDROID に XR_TRACKABLE_TYPE_IMAGE_ANDROID が追加されます。

アプリは、xrCreateTrackableTrackerANDROID を呼び出し、XrTrackableTrackerCreateInfoANDROID :: trackableType でトラッキング可能なタイプとして XR_TRACKABLE_TYPE_IMAGE_ANDROID を指定することで、XrTrackableTrackerANDROID を作成できます。

ランタイムは、XrTrackableTrackerCreateInfoANDROID :: trackableType が XR_TRACKABLE_TYPE_IMAGE_ANDROID で、XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking が xrGetSystemProperties を介して XR_FALSE を返す場合、XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • databaseCount は、databases 内の要素数を指定する uint32_t です。
  • databases は、トラッカーの作成に使用するデータベースを指定する XrTrackableImageDatabaseANDROID の配列です。

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

アプリケーションは、トラッカーの作成に使用する XrTrackableImageDatabaseANDROID 構造を少なくとも 1 つ提供しなければなりません。

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

XrTrackableImageTrackingModeANDROID 列挙型は、サポートされている画像のトラッキング モードを表します。

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

列挙体の説明

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID - このモードは精度が最も高く、低レイテンシで動画をトラッキングできます。また、消費電力も最も高くなります。
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID - 静的または半静的であることがわかっている画像には、このモードを使用する必要があります。このモードでは、動的モードに比べて消費電力が少なくなります。静止画像を移動する場合、動的モードを使用する場合よりもはるかに高いレイテンシで更新されます。

XrTrackableImageFormatANDROID 列挙型は、サポートされている画像の形式を表します。

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

列挙体の説明

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID - チャンネルあたり 8 ビットの色と透明度のデータを含む RGBA 画像形式。

xrAddTrackableImageDatabaseANDROID 関数は次のように定義されます。

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

パラメータの説明

XrTrackableImageDatabaseANDROID がトラッカーに追加されると、そのデータベースの参照画像は、xrAddTrackableImageDatabaseANDROID または XrTrackableImageConfigurationANDROID 構造体を使用してトラッカーの初期作成時に以前に追加された他のデータベースに加えて、検出とトラッキングの対象にしなければなりません。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

xrRemoveTrackableImageDatabaseANDROID 関数は次のように定義されます。

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

パラメータの説明

XrTrackableImageDatabaseANDROID が XrTrackableTrackerANDROID から削除された場合、そのデータベースの XrTrackableImageDatabaseEntryANDROID 構造は検出とトラッキングの対象から外さなければなりません。そのデータベースのアクティブに追跡されているエントリは、報告されなくなります。削除された XrTrackableImageDatabaseANDROID ハンドルは、このオペレーションの一部として暗黙的に破棄されてはなりません。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

画像を取得しています

xrGetTrackableImageANDROID 関数は次のように定義されます。

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

パラメータの説明

XrTrackableANDROID の追跡可能な型が XR_TRACKABLE_TYPE_IMAGE_ANDROID でない場合、または XrTrackableTrackerANDROID の追跡可能な型が XR_TRACKABLE_TYPE_IMAGE_ANDROID でない場合、ランタイムは XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID を返さなければなりません。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • trackingState は、画像の XrTrackingStateANDROID です。
  • lastUpdatedTime は、イメージの最後の更新の XrTime です。
  • database は、この画像がトラッキングされた XrTrackableImageDatabaseANDROID ハンドルです。
  • databaseEntryIndex は、XrTrackableImageDatabaseCreateInfoANDROID :: entries 配列の database にマッピングされるインデックスです。
  • centerPose は、XrTrackableGetInfoANDROID :: baseSpace にある画像の XrPosef です。画像は XZ 平面にあり、X は画像の右方向、Z は下方向を指します。
  • extents は、画像の XrExtent2Df のディメンションです。境界ボックスの境界は、centerPose +/-（extents / 2）のポイントにあります。

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

障害対応

アプリケーションは、xrPollEvent を使用して XrEventDataImageTrackingLostANDROID イベントをポーリングし、無視してはなりません。

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • time XrTime

XrEventDataImageTrackingLostANDROID イベントを受け取った場合、画像トラッキングで内部障害が発生し、既存のリソースが無効になったことを示します。画像トラッキングを継続する場合、アプリケーションはすべての XrTrackableImageDatabaseANDROID ハンドルを破棄し、再作成しなければなりません。また、アプリケーションは、画像トラッキングを継続したい場合は、画像トラッキングに関連するすべての XrTrackableTrackerANDROID ハンドルを破棄し、再作成する必要があります。

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

追跡可能な画像を取得するサンプルコード

次のサンプルコードは、追跡可能な画像を取得する方法を示しています。

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

実行時に画像データベースを管理するコード例

次のコード例は、トラッキング対象の画像セットを変更する方法を示しています。

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

画像トラッキングの失敗に対応するサンプルコード

次のサンプルコードは、XrEventDataImageTrackingLostANDROID イベントをポーリングして失敗を処理する方法を示しています。

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

新しいオブジェクト タイプ

新しいコマンド

新しい構造体

新しい列挙型

新しい列挙型定数

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION

  • XrObjectType の拡張 :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID

  • XrResult の拡張 :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID

  • XrStructureType を拡張する :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID

  • XrTrackableTypeANDROID を拡張する :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

問題

変更履歴

  • リビジョン 1、2025 年 4 月 8 日（Daniel Guttenberg）

    • 拡張機能の初回説明。