XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

拡張機能の種類

インスタンス拡張

登録済みの内線番号

783

リビジョン

1

承認ステータス

未批准

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

XR_EXT_spatial_entity

寄与者

Daniel Guttenberg、Qualcomm
Nihav Jain、Google
Jared Finder、Google
Zhipeng Liu、ByteDance

概要

この拡張機能は、XR_EXT_spatial_entity 拡張機能に画像トラッキング機能を提供します。これにより、アプリケーションは、入力参照画像のセットで指定された特定の平面画像を検出して追跡できます。

トラッキングされた画像は、次のコンポーネントを持つ空間エンティティとして表されます。

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

アプリケーションは通常、次のパターンで空間画像トラッキング拡張機能を使用します。

  • アプリケーションはまず、プリロードされた参照画像データのセットに基づいて 1 つ以上の XrSpatialImageTrackingDatabaseEXT ハンドルを作成します。
  • 次に、アプリケーションは、以前に作成した XrSpatialImageTrackingDatabaseEXT ハンドルに基づいて XrSpatialContextEXT ハンドルを作成します。
  • その後、アプリケーションは参照画像データを解放してメモリ消費量を削減します。
  • アプリケーションは、空間エンティティのアクセス パターンに従って画像を検出してクエリします。
  • アプリケーションは、参照画像の追加セットを読み込み、追加の XrSpatialImageTrackingDatabaseEXT を作成し、その後、それらから XrSpatialContextEXT を作成して、実行時に検出可能および追跡可能な画像のセットを動的に拡張できます。
  • アプリケーションは、XrSpatialImageTrackingDatabaseEXT ハンドルを破棄して、実行時に検出可能および追跡可能な画像のセットを動的に減らすことができます。
  • アプリケーションは、XrSpatialContextEXT ハンドルを破棄して、実行時に検出可能および追跡可能な画像のセットを動的に減らすことができます。

ランタイム サポート

ランタイムは、xrEnumerateSpatialCapabilitiesEXT を使用して、次の機能をリストすることで、画像トラッキング機能のサポートをアドバタイズしなければなりません。

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

構成

平面画像の検出とトラッキングを有効にするには、アプリケーションは、xrCreateSpatialContextAsyncEXT 関数を呼び出すときに、XrSpatialContextCreateInfoEXT :: capabilityConfigs で XrSpatialCapabilityConfigurationImageTrackingEXT 構造体を渡すことができます。また、各 XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases で XrSpatialImageTrackingDatabaseEXT 構造体の配列を渡すことができます。

入力画像セットの作成

検出および追跡する参照画像を指定するには、アプリで少なくとも 1 セットの入力参照画像を作成する必要があります。入力参照画像のセットは XrSpatialImageTrackingDatabaseEXT ハンドルで表され、少なくとも 1 つの画像が含まれます。

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

XrSpatialImageTrackingDatabaseEXT ハンドルは、ユーザーの環境でいくつかの空間画像を検出して更新するためのリソースを表します。アプリケーションは、このハンドルを使用して、この拡張機能の他の関数を使用して空間画像を検出して更新できます。

空間画像トラッキング データベースを作成する

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

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

パラメータの説明

  • session は、空間画像トラッキング データベースがアクティブになる XrSession です。
  • createInfo は、空間画像トラッキング データベースのパラメータを指定するために使用される XrSpatialImageTrackingDatabaseCreateInfoEXT です。
  • future は XrFutureEXT へのポインタです。

アプリは、xrCreateSpatialImageTrackingDatabaseAsyncEXT 関数を使用して XrSpatialImageTrackingDatabaseEXT ハンドルを作成し、createInfo を使用して画像トラッキング データベースの入力参照画像のセットを構成できます。

入力参照画像の XrSpatialReferenceImageEXT :: format が xrEnumerateSpatialReferenceImageFormatsEXT によって列挙されていない場合、ランタイムは XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT を返さなければなりません。

XrSpatialReferenceImageEXT の参照画像メタデータに従って、入力参照画像の XrSpatialReferenceImageEXT :: planes 配列を評価できない場合、ランタイムは XR_ERROR_SPATIAL_IMAGE_INVALID_EXT を返さなければなりません。

ランタイムは、入力参照画像の XrSpatialReferenceImageEXT :: planes 配列が XrSpatialReferenceImageEXT :: format のカラー チャンネルと同じ数の平面を提供しない場合、XR_ERROR_SPATIAL_IMAGE_INVALID_EXT を返さなければなりません。

ランタイムが権限システムを適用して、画像トラッキング機能へのアプリケーション アクセスを制御する場合、ランタイムは、それらの権限がこのアプリケーションに付与されていない場合、XR_ERROR_PERMISSION_INSUFFICIENT を返さなければなりません。

この関数は非同期オペレーションを開始し、対応する XrFutureEXT を作成します。これは xrPollFutureEXT および関連する関数で使用できます。この関数の戻り値は、パラメータが非同期オペレーションのスケジュール設定に許容されるかどうかのみを示します。対応する完了関数は xrCreateSpatialImageTrackingDatabaseCompleteEXT です。この関数からのフューチャーが READY 状態のときに使用でき、その関数によって出力が完了構造 XrCreateSpatialImageTrackingDatabaseCompletionEXT に入力されます。

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

戻りコード

成功

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • spatialReferenceImageCount は、spatialReferenceImages 配列内の要素数です。
  • spatialReferenceImages は XrSpatialReferenceImageEXT の配列です。

XrSpatialImageTrackingDatabaseCreateInfoEXT 構造体は、XrSpatialImageTrackingDatabaseEXT ハンドルを作成するための情報を記述します。

各 XrSpatialImageTrackingDatabaseEXT は、XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 配列に少なくとも 1 つの XrSpatialReferenceImageEXT を含めて作成しなければなりません。

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

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

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

パラメータの説明

xrCreateSpatialImageTrackingDatabaseCompleteEXT は、xrCreateSpatialImageTrackingDatabaseAsyncEXT によって開始された非同期オペレーションを完了します。

ランタイムは、この xrCreateSpatialImageTrackingDatabaseAsyncEXT 呼び出しの XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 入力配列によって提供された XrSpatialReferenceImagePlaneEXT :: buffer ポインタに、呼び出しの完了後にアクセスしてはなりません。アプリケーションは、xrCreateSpatialImageTrackingDatabaseAsyncEXT の完了後に XrSpatialReferenceImagePlaneEXT :: buffer データを解放して、メモリ使用量を削減できます。

future が準備完了状態でない場合、ランタイムは XR_ERROR_FUTURE_PENDING_EXT を返さなければなりません。future がすでに完了またはキャンセルされている場合、ランタイムは XR_ERROR_FUTURE_INVALID_EXT を返さなければなりません。

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

戻りコード

成功

  • 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

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

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

メンバーの説明

今後の返品コード

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
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

futureResult が成功コードの場合、database は有効なハンドルである必要があります。database が有効な場合、xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session のライフサイクル内、またはアプリが xrDestroySpatialImageTrackingDatabaseEXT で database を破棄するまで（いずれか早い方）のみ有効です。

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

空間画像トラッキング データベースを破棄する

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

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

パラメータの説明

アプリは、空間画像の検出と更新のタスクが完了したときに、xrDestroySpatialImageTrackingDatabaseEXT 関数を呼び出して database ハンドルと基盤となるリソースを解放できます。

アプリは、xrDestroySpatialContextEXT を呼び出す前に xrDestroySpatialImageTrackingDatabaseEXT 関数を呼び出すことができます。ランタイムは、この破棄された XrSpatialImageTrackingDatabaseEXT によって管理されている画像を報告してはなりません。ランタイムは、他のデータベースによって管理されているイメージを引き続き報告しなければなりません。

ランタイムは、xrCreateSpatialDiscoverySnapshotCompleteEXT によって返される検出スナップショットに、破棄された、または無効な XrSpatialImageTrackingDatabaseEXT ハンドルに関連する画像が含まれないようにしなければなりません。これは、アプリケーションが xrCreateSpatialDiscoverySnapshotAsyncEXT を呼び出した後にハンドルが破棄された場合でも同様です。空間スナップショット内のデータは不変であるため、アプリは database を破棄する前に作成された XrSpatialSnapshotEXT ハンドルを破棄すべきです。そうしないと、アプリは xrQuerySpatialComponentDataEXT を使用するときに無効な XrSpatialImageTrackingDatabaseEXT ハンドルを受け取る可能性があります。

アプリケーションは、xrDestroySpatialContextEXT 関数を呼び出して XrSpatialContextEXT ハンドルを解放してから、XrSpatialContextEXT の作成に使用された XrSpatialImageTrackingDatabaseEXT ハンドルを破棄できます。ランタイムは、XrSpatialContextEXT が破棄されたときに、これらの XrSpatialImageTrackingDatabaseEXT ハンドルを暗黙的に破棄してはなりません。

XrSpatialContextEXT と XrSpatialImageTrackingDatabaseEXT のライフタイムを個別に管理することで、アプリは、コストのかかる作成手順を再度実行することなく、以前に作成した XrSpatialImageTrackingDatabaseEXT ハンドルを再利用できます。

たとえば、XrSpatialContextEXT を破棄し、その後、同じ XrSpatialImageTrackingDatabaseEXT を使用して別の XrSpatialContextEXT を再作成すると、別の初期化手順を実行することなく、画像トラッキングの一時停止と再開が可能になります。

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

スレッドセーフ

  • database とその子ハンドルへのアクセスは、外部で同期する必要があります。

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

入力画像形式のサポート

アプリは、xrEnumerateSpatialReferenceImageFormatsEXT を呼び出して、サポートされている入力参照画像形式のリストを取得すべきです。

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

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

パラメータの説明

  • instance は XrInstance のハンドルです。
  • systemId は、入力参照画像形式が列挙される XrSystemId です。
  • capability は、入力参照画像形式が列挙される XrSpatialCapabilityEXT です。
  • formatCapacityInput は formats 配列の容量です。0 の場合は、必要な容量を取得するリクエストであることを示します。
  • formatCountOutput は、フォーマットの数、または formatCapacityInput が不十分な場合に必要となる容量です。
  • formats は XrSpatialReferenceImageFormatEXT の配列です。formatCapacityInput が 0 の場合、NULL になることがあります。
  • 必要な formats サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

アプリは、xrEnumerateSpatialReferenceImageFormatsEXT を使用して、特定の XrSpatialCapabilityEXT に対して特定の XrSystemId でサポートされている入力参照画像形式のリストを列挙できます。

ランタイムは、instance で有効になっていない拡張機能の形式を列挙してはなりません。

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

  • xrEnumerateSpatialReferenceImageFormatsEXT を呼び出す前に、XR_EXT_spatial_image_tracking 拡張機能を有効にする必要があります。
  • instance は、有効な XrInstance ハンドルでなければなりません。
  • capability は、有効な XrSpatialCapabilityEXT 値でなければなりません
  • formatCountOutput は uint32_t 値へのポインタでなければなりません
  • formatCapacityInput が 0 でない場合、formats は formatCapacityInput XrSpatialReferenceImageFormatEXT 値の配列へのポインタでなければなりません。

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

拡張機能でサポートされているすべての参照画像形式の一覧については、XrSpatialReferenceImageFormatEXT をご覧ください。

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

XrSpatialReferenceImageFormatEXT 列挙型は、ランタイムがサポートする可能性のある入力参照画像形式を識別します。

少なくとも XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT 値と XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT 値をサポートしなければなりません。

列挙子の意味は次のとおりです。

列挙子の説明

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT - RGBA バッファ。この形式では、メモリ内のピクセルデータのレイアウトは保証されません。ピクセルには、対応する XrSpatialReferenceImagePlaneEXT 構造体によって提供されるメタデータを使用してアクセスしなければなりません。各ピクセルのカラー チャンネルのサイズは 8 ビットで、各ピクセルのサイズは 32 ビットです。
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT - RGB バッファ。この形式では、メモリ内のピクセルデータのレイアウトは保証されません。ピクセルには、対応する XrSpatialReferenceImagePlaneEXT 構造体によって提供されるメタデータを使用してアクセスしなければなりません。各ピクセルのカラー チャンネルは 8 ビットサイズで、各ピクセルのサイズは 24 ビットです。
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT - 4:2:0 パターンのクロマ サブサンプリングが適用された YUV バッファ。この形式では、メモリ内のピクセルデータのレイアウトは保証されません。ピクセルには、対応する XrSpatialReferenceImagePlaneEXT 構造体によって提供されるメタデータを使用してアクセスしなければなりません。デコードされた RGB ピクセルの各カラー チャンネルは 8 ビットサイズで、各ピクセルは 24 ビットサイズになります。

空間画像トラッキングの設定

この拡張機能には、アプリケーションが画像トラッキング機能を構成するために使用できるオプションの構造体が用意されています。

静止画像の最適化

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

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • optimizeForStaticImage は、画像が移動するかどうかを示す XrBool32 です。値 XR_TRUE は、画像が移動しないことを示します。

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT が XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 機能の xrEnumerateSpatialCapabilityFeaturesEXT によって列挙されている場合、アプリは XrSpatialImageStaticOptimizationEXT を XrSpatialImageTrackingDatabaseCreateInfoEXT :: next チェーンまたは XrSpatialReferenceImageEXT :: next にチェーンできます。

アプリが XrSpatialImageStaticOptimizationEXT を XrSpatialImageTrackingDatabaseCreateInfoEXT 構造にチェーンする場合、optimizeForStaticImage が XR_TRUE に設定されている場合、ランタイムは、その XrSpatialImageTrackingDatabaseEXT のすべての画像が静的であると想定しなければなりません。これに対応して、optimizeForStaticImage が XR_FALSE に設定されている場合、ランタイムは、その XrSpatialImageTrackingDatabaseEXT のすべての画像が静的ではないと想定しなければなりません。

アプリケーションが XrSpatialImageStaticOptimizationEXT を XrSpatialReferenceImageEXT 構造体にチェーンする場合、optimizeForStaticImage が XR_TRUE に設定されている場合、ランタイムは、この参照画像が静的であると想定しなければなりません。これに対応して、optimizeForStaticImage が XR_FALSE に設定されている場合、ランタイムは、この参照画像が静的でないと想定しなければなりません。XrSpatialImageStaticOptimizationEXT 構造体を XrSpatialReferenceImageEXT 構造体にチェーンすることは、XrSpatialImageTrackingDatabaseCreateInfoEXT 構造体にチェーンすることよりも優先されます。

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT が XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 機能の xrEnumerateSpatialCapabilityFeaturesEXT によって列挙されず、アプリが XrSpatialImageStaticOptimizationEXT 構造体を該当する次のチェーンのいずれかにチェーンする場合、ランタイムは xrCreateSpatialImageTrackingDatabaseAsyncEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

これにより、ランタイムがより正確なポーズとサイズを生成できる可能性があります。

これにより、ランタイムの消費電力を削減できる可能性があります。

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

参照画像の幅

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

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • physicalWidth は、設定する物理的な幅（メートル単位）を表す float 値です。

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 機能に対して xrEnumerateSpatialCapabilityFeaturesEXT によって XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT が列挙されている場合、アプリは XrSpatialImageSizeEXT を XrSpatialImageTrackingDatabaseCreateInfoEXT :: next または XrSpatialReferenceImageEXT :: next にチェーンできます。

アプリケーションが XrSpatialImageSizeEXT を XrSpatialImageTrackingDatabaseCreateInfoEXT 構造体にチェーンする場合、ランタイムは、その XrSpatialImageTrackingDatabaseEXT のすべての画像の幅が physicalWidth メートルで、高さが XrSpatialReferenceImageEXT :: width と XrSpatialReferenceImageEXT :: height を通じて暗黙的に提供されるアスペクト比に従っていると想定しなければなりません。

アプリが XrSpatialImageSizeEXT を XrSpatialReferenceImageEXT 構造体にチェーンする場合、ランタイムは、この参照画像の幅が physicalWidth メートルで、高さが XrSpatialReferenceImageEXT :: width と XrSpatialReferenceImageEXT :: height を介して暗黙的に提供されるアスペクト比に従っていると想定しなければなりません。XrSpatialImageSizeEXT 構造体を XrSpatialReferenceImageEXT 構造体にチェーンすることは、XrSpatialImageTrackingDatabaseCreateInfoEXT 構造体にチェーンすることよりも優先されます。

これにより、ランタイムがより正確なポーズとサイズを返す可能性があります。

ランタイムは、XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT または XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT、あるいはその両方を列挙しなければなりません。

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT が xrEnumerateSpatialCapabilityFeaturesEXT によって列挙される場合、ランタイムは、アプリケーションが該当する次のチェーンの一部として XrSpatialImageSizeEXT 構造を提供しなかった画像に対して、画像サイズを自動的に提供しなければなりません。

ランタイムが画像サイズを自動的かつ正確に生成できるようにするには、特定のデバイス機能と前提条件が必要になる場合があります。たとえば、ステレオ カメラ、正確に調整されたカメラの外部パラメータと内部パラメータなどです。

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT が xrEnumerateSpatialCapabilityFeaturesEXT によって列挙されない場合、アプリは XrSpatialImageSizeEXT 構造体を該当する次のチェーンにリンクして、すべての画像に明示的なサイズが指定されるようにしなければなりません。そうしない場合、ランタイムは xrCreateSpatialImageTrackingDatabaseAsyncEXT から XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT を返さなければなりません。

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

  • XrSpatialImageSizeEXT を使用する前に、XR_EXT_spatial_image_tracking 拡張機能を有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_IMAGE_SIZE_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

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

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • capability は XrSpatialCapabilityEXT であり、XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT でなければなりません。
  • enabledComponentCount は、enabledComponents の要素数を指定する uint32_t です。
  • enabledComponents は、この機能で有効にするコンポーネントを指定する XrSpatialComponentTypeEXT の配列です。
  • imageTrackingDatabaseCount は、imageTrackingDatabases の要素数を指定する unint32_t です。
  • imageTrackingDatabases は、空間コンテキストで有効にする画像トラッキング データベースを指定する XrSpatialImageTrackingDatabaseEXT ハンドルの配列です。

画像トラッキングがサポートされている場合、xrCreateSpatialContextAsyncEXT の呼び出し時に XrSpatialContextCreateInfoEXT :: capabilityConfigs で XrSpatialCapabilityConfigurationImageTrackingEXT 構造体が渡されると、ランタイムは画像トラッキングを有効にしなければなりません。

XrSpatialCapabilityConfigurationImageTrackingEXT 構造により、アプリは imageTrackingDatabases の XrSpatialImageTrackingDatabaseEXT ハンドルで表される参照画像を検出できます。

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT が xrEnumerateSpatialCapabilitiesEXT によって列挙されていない場合、ランタイムは XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT を返さなければなりません。

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

  • XrSpatialCapabilityConfigurationImageTrackingEXT を使用する前に、XR_EXT_spatial_image_tracking 拡張機能を有効にする必要があります。
  • type は XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • capability は、有効な XrSpatialCapabilityEXT 値でなければなりません
  • enabledComponents は、enabledComponentCount 個の有効な XrSpatialComponentTypeEXT 値の配列へのポインタでなければなりません。
  • imageTrackingDatabases は、imageTrackingDatabaseCount 個の有効な XrSpatialImageTrackingDatabaseEXT ハンドルの配列へのポインタでなければなりません
  • enabledComponentCount パラメータは 0 より大きい値にする必要があります。
  • imageTrackingDatabaseCount パラメータは 0 より大きい値にする必要があります。

空間参照画像

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

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

パラメータの説明

  • bufferSize は buffer 配列のサイズです。
  • buffer は、平面データを表す uint8_t データの配列です。
  • rowStride は、連続するピクセルデータ行の 2 つの開始位置間のバイト距離です。
  • pixelStride は、連続する 2 つのピクセル間のバイト距離です。

ランタイムは、rowStride パラメータと pixelStride パラメータが提供するパターンに従って buffer にアクセスする必要があります。

アプリケーションは、この XrSpatialReferenceImagePlaneEXT の意味のあるピクセルのみがランタイムによって抽出されるように、rowStride と pixelStride を設定しなければなりません。

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

  • XrSpatialReferenceImagePlaneEXT を使用する前に、XR_EXT_spatial_image_tracking 拡張機能を有効にしなければなりません。
  • buffer は、bufferSize uint8_t 値の配列へのポインタでなければなりません
  • bufferSize パラメータは 0 より大きい値にする必要があります。

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

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

パラメータの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • width は、参照画像のピクセル幅です。
  • height は、参照画像のピクセル単位の高さです。
  • format は、画像の形式を表す XrSpatialReferenceImageFormatEXT です。
  • planeCount は、planes 配列内の要素数です。
  • planes は、画像データの平面を表す XrSpatialReferenceImagePlaneEXT 構造体の配列です。

アプリは、XrSpatialImageTrackingDatabaseEXT ハンドルの作成時に、XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages を介して xrCreateSpatialImageTrackingDatabaseAsyncEXT 関数に渡される単一の入力参照画像を表す 1 つ以上の XrSpatialReferenceImageEXT 構造体を作成できます。

XrSpatialReferenceImagePlaneEXT :: buffer データは、アプリケーションによって左から右、上から下のピクセル順序で提供しなければなりません。

アプリケーションは、XrSpatialReferenceImageEXT :: format の各カラー チャンネルに対して、XrSpatialReferenceImageEXT :: planes 配列に XrSpatialReferenceImagePlaneEXT 構造体を指定しなければなりません。

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

保証対象の部品

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT をサポートするランタイムは、それらの機能によって検出されたすべてのエンティティの保証されたコンポーネントとして、次の空間コンポーネントを提供しなければならず、xrEnumerateSpatialCapabilityComponentTypesEXT でそれらを列挙しなければなりません。

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

画像 2D コンポーネント

クエリデータへのコンポーネント リスト構造体

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

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

パラメータの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • imageCount は、images 配列内の要素数です。
  • images は XrSpatialImage2DDataEXT の配列です。

XrSpatialComponentImage2DListEXT が XrSpatialComponentDataQueryResultEXT :: next チェーンに含まれているが、XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT が XrSpatialComponentDataQueryConditionEXT :: componentTypes に含まれていない場合、ランタイムは xrQuerySpatialComponentDataEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

imageCount が XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput より小さい場合、ランタイムは xrQuerySpatialComponentDataEXT から XR_ERROR_SIZE_INSUFFICIENT を返さなければなりません。

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

  • XrSpatialComponentImage2DListEXT を使用する前に、XR_EXT_spatial_image_tracking 拡張機能を有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • images は、imageCount 個の XrSpatialImage2DDataEXT 構造体の配列へのポインタでなければなりません
  • imageCount パラメータは 0 より大きい値にする必要があります。
コンポーネント データ

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

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

パラメータの説明

アプリケーションは、imageTrackingDatabase を使用して、以前に作成された XrSpatialImageTrackingDatabaseEXT のうち、この XrSpatialImage2DDataEXT 構造体の参照画像を含むものを特定できます。その XrSpatialImageTrackingDatabaseEXT の場合、アプリケーションは referenceImageIndex を使用して、XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 配列の入力順序と一致させることで、この XrSpatialImage2DDataEXT 構造の XrSpatialReferenceImageEXT を識別できます。

すべてのアクティブなデータベースのセットによって定義される参照画像のセットに、重複する画像を含めるべきではありません。重複する画像を含めると、検出やトラッキングの動作に悪影響を及ぼす可能性があります。たとえば、一貫性のないインデックスや複数のインデックスが返されることがあります。

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

構成

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT が、ある機能の XrSpatialCapabilityComponentTypesEXT :: componentTypes で列挙されている場合、アプリは、XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents リストに列挙値を含めることで、その機能を有効にできます。このコンポーネントでは、XrSpatialCapabilityConfigurationBaseHeaderEXT の次のチェーンに含めるための特別な構成は必要ありません。

境界付き 2D コンポーネント

境界付き 2D コンポーネントは、それが配置されているエンティティによって表される空間画像の中心と範囲を提供します。境界付き 2D コンポーネントの詳細については、境界付き 2D をご覧ください。

コード例

空間画像とクエリ コンポーネント データを検出する

次のサンプルコードは、画像トラッキング機能の空間エンティティを検出し、そのコンポーネント データをクエリする方法を示しています。

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

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

新しいコマンド

新しい構造

新しい列挙型

新しい列挙型定数

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • XrObjectType の拡張:

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • XrResult の拡張:

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • XrSpatialCapabilityEXT の拡張:

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • XrSpatialCapabilityFeatureEXT の拡張:

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • XrSpatialComponentTypeEXT の拡張:

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • XrStructureType の拡張:

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

問題

変更履歴

  • リビジョン 1、2025-04-22（Daniel Guttenberg、Qualcomm）

    • 拡張機能の初期説明