XR_ANDROID_trackables_marker

名稱字串

XR_ANDROID_trackables_marker

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

708

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_ANDROID_trackables

淘汰狀態

  • 已淘汰 XR_EXT_spatial_marker_tracking 擴充功能

上次修改日期

2025-07-23

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 Tags。這可讓執行階段選擇性支援標記大小估算。

權限

Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_COARSE 權限，因為這項擴充功能會公開環境的幾何結構，並依附於 XR_ANDROID_trackables。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 時，使用 XrSystemMarkerTrackingPropertiesANDROID 結構體擴充 XrSystemProperties，檢查系統是否支援標記追蹤功能。如果 supportsMarkerTracking 為 XR_FALSE，則只有在執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED 時，才能建立標記追蹤器。

如果執行階段支援標記追蹤，maxMarkerCount 必須至少為 1。

有效使用 (隱含)

  • XR_ANDROID_trackables_marker 擴充功能必須先啟用，才能使用 XrSystemMarkerTrackingPropertiesANDROID
  • type 必須為 XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標

追蹤標記

這項擴充功能會將 XR_TRACKABLE_TYPE_MARKER_ANDROID 新增至 XrTrackableTypeANDROID。

應用程式會呼叫 xrCreateTrackableTrackerANDROID 並在 XrTrackableTrackerCreateInfoANDROID :: trackableType 中指定 XR_TRACKABLE_TYPE_MARKER_ANDROID 做為可追蹤型別，藉此建立 XrTrackableTrackerANDROID，並在 XrTrackableTrackerCreateInfoANDROID 的下一個鏈結中新增 XrTrackableMarkerConfigurationANDROID，藉此設定有效設定。

如果 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;

成員說明

應用程式必須新增 XrTrackableMarkerConfigurationANDROID 至 XrTrackableTrackerCreateInfoANDROID :: next 鏈結，藉此設定有效設定，並使用 XrTrackableTrackerCreateInfoANDROID :: trackableType 設為 XR_TRACKABLE_TYPE_MARKER_ANDROID 呼叫 xrCreateTrackableTrackerANDROID。否則，如果追蹤器類型設為上述類型，但設定結構不存在或無效，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果執行階段支援標記大小估算，應用程式可以在 XrTrackableMarkerDatabaseANDROID :: entries 中將 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize 設為 0，表示要使用大小估算功能。否則，應用程式必須將 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize 設為正值，或執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

執行階段必須篩選 xrGetAllTrackablesANDROID 的輸出內容，以符合 trackingMode 和 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize。

有效使用 (隱含)

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;

成員說明

有效使用 (隱含)

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 代表標記邊緣的大小 (以公尺為單位)。如果執行階段支援標記大小估算，應用程式可以將此值設為零，系統會線上估算標記大小。如果設為零，但執行階段不支援標記大小估算，執行階段必須傳回 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 中的標記 XrPosef，:: baseSpace。標記位於 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)

    • 擴充功能說明。