XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

708

リビジョン

1

Ratification Status（批准ステータス）

未批准

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

XR_ANDROID_trackables

非推奨の状態

  • XR_EXT_spatial_marker_tracking 拡張機能により非推奨

最終更新日

2025-07-23

IP ステータス

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

寄与者

Christopher Doer（Google）
Diego Tipaldi（Google）
Levana Chen（Google）
Jared Finder（Google）
Spencer Quin（Google）
Nihav Jain（Google）
Ken Mackay（Google）
Daniel Guttenberg（Qualcomm）

概要

この拡張機能により、物理マーカーのトラッキングが可能になり、アプリが XR コンテンツを物理マーカーに効率的に関連付けることができます。

この拡張機能は、よく知られているマーカー タイプ（特に ArUco と April タグ）をサポートしています。これにより、ランタイムでマーカー サイズの推定を任意でサポートできるようになります。

権限

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

（保護レベル: 危険）

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

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

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。構造チェーンの詳細については、拡張される構造（XrSystemProperties）をご覧ください。
  • supportsMarkerTracking は、現在のシステムがマーカー追跡機能を提供するかどうかを示す XrBool32 です。
  • supportsMarkerSizeEstimation は、現在のシステムがマーカー サイズの推定を提供するかどうかを示す XrBool32 です。
  • maxMarkerCount は、ランタイムが同時に追跡できるマーカーの最大数です。

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

ランタイムがマーカー トラッキングをサポートしている場合、maxMarkerCount は 1 以上にする必要があります。

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

トラッキング マーカー

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

アプリケーションは、xrCreateTrackableTrackerANDROID を呼び出し、XrTrackableTrackerCreateInfoANDROID :: trackableType でトラッキング可能なタイプとして XR_TRACKABLE_TYPE_MARKER_ANDROID を指定し、XrTrackableTrackerCreateInfoANDROID の次のチェーンに XrTrackableMarkerConfigurationANDROID を追加して有効な構成を設定することで、XrTrackableTrackerANDROID を作成します。

ランタイムは、XrTrackableTrackerCreateInfoANDROID :: trackableType が XR_TRACKABLE_TYPE_MARKER_ANDROID で、XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking が xrGetSystemProperties 経由で XR_FALSE を返す場合、XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

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

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • trackingMode は、トラッキングの目的のモードを示す XrTrackableMarkerTrackingModeANDROID です。
  • databaseCount は、databases 配列内の要素の数を記述する uint32_t です。
  • databases は XrTrackableMarkerDatabaseANDROID の配列へのポインタです。各配列には、追跡する特定の辞書から必要なマーカーが含まれています。

アプリケーションは、XrTrackableTrackerCreateInfoANDROID :: trackableType を XR_TRACKABLE_TYPE_MARKER_ANDROID に設定して xrCreateTrackableTrackerANDROID を呼び出す際に、XrTrackableTrackerCreateInfoANDROID :: next チェーンに XrTrackableMarkerConfigurationANDROID を追加して、有効な構成を設定しなければなりません。それ以外の場合、トラッカー タイプが上記のように設定されていても、構成構造が存在しないか有効でない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

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

ランタイムは、trackingMode および XrTrackableMarkerDatabaseEntryANDROID :: edgeSize に一致するように xrGetAllTrackablesANDROID からの出力をフィルタしなければなりません。

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

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

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

列挙体の説明

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID - 動的マーカーのトラッキング。このモードは精度が最も高く、移動マーカーと静止マーカーの両方で動作しますが、消費電力も最も高くなります。
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID - 静的マーカーをトラッキングします。このモードは、主に静的であることがわかっているマーカーに役立ちます。動的モードと比較して、消費電力を抑えることができます。

XrTrackableMarkerDatabaseANDROID 構造体は、トラッキングするディクショナリと対応するマーカー ID を定義します。

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

メンバーの説明

  • dictionary は、すべての entries が属する XrTrackableMarkerDictionaryANDROID です。
  • entryCount は、entries 配列内の要素の数を記述する uint32_t です。アプリケーションは、entryCount 0 を設定して、dictionary 内のすべてのマーカーをトラッキングできます。
  • entries は XrTrackableMarkerDatabaseEntryANDROID の配列へのポインタです。各エントリには、追跡するマーカーの構成が含まれています。

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

XrTrackableMarkerDictionaryANDROID 列挙型は、サポートされているマーカー ディクショナリを記述します。

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

XrTrackableMarkerDatabaseEntryANDROID 構造体は、ディクショナリの単一のマーカー ID を構成します。

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

メンバーの説明

  • id は、辞書で指定されたマーカー ID です。
  • edgeSize は、マーカーの端のサイズをメートル単位で表します。ランタイムがマーカー サイズの推定をサポートしている場合、アプリケーションはこれを 0 に設定でき、マーカー サイズはオンラインで推定されます。これがゼロに設定されていても、ランタイムがマーカー サイズの推定をサポートしていない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

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

マーカーを取得する

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

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

パラメータの説明

XrTrackableANDROID の追跡可能な型が XR_TRACKABLE_TYPE_MARKER_ANDROID でない場合、または XrTrackableTrackerANDROID の追跡可能な型が XR_TRACKABLE_TYPE_MARKER_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_LIMIT_REACHED
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • trackingState はマーカーの XrTrackingStateANDROID です。
  • lastUpdatedTime は、マーカーの最終更新の XrTime です。
  • dictionary はマーカーの XrTrackableMarkerDictionaryANDROID です。
  • markerId は、辞書で指定されたマーカー ID です。
  • centerPose は、XrTrackableGetInfoANDROID :: baseSpace にあるマーカーの XrPosef です。マーカーは XZ 平面にあり、X はマーカーの右方向、Z はマーカーの下方向、Y はマーカーから外向きの法線です。
  • extents は、マーカーの XrExtent2Df の寸法です。境界ボックスの境界は、centerPose +/-（extents / 2）のポイントにあります。

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

追跡可能なマーカーを取得するコードの例

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

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_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // 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
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

新しいコマンド

新しい構造体

新しい列挙型

新しい列挙型定数

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • XrStructureType を拡張する :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID を拡張する :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

問題

変更履歴

  • リビジョン 1、2025-07-23（Levana Chen）

    • 拡張機能の初回説明。