Android XR for OpenXR | Android Developers

Android 開發人員高峰會再度登場，並專為 Android XR 規劃一系列議程。歡迎試用，並提供意見！

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

708

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

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 和 AprilTag。執行階段可選擇是否支援標記大小估算。

權限

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;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。
trackingMode 是 XrTrackableMarkerTrackingModeANDROID，表示所需的追蹤模式。
databaseCount 是 uint32_t，用於描述 databases 陣列中的元素數量。
databases 是 XrTrackableMarkerDatabaseANDROID 陣列的指標，每個陣列都包含要追蹤的指定字典中的所需標記。

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

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

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

有效用途 (隱含)

必須先啟用 XR_ANDROID_trackables_marker 擴充功能，才能使用 XrTrackableMarkerConfigurationANDROID
type「必須」為 XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
trackingMode「必須」是有效的 XrTrackableMarkerTrackingModeANDROID 值
databases「必須」是指向 databaseCount 個有效 XrTrackableMarkerDatabaseANDROID 結構陣列的指標
databaseCount 參數必須大於 0

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 是 uint32_t，用於描述 entries 陣列中的元素數量。應用程式可以設定 entryCount 0，追蹤 dictionary 中的所有標記。
entries 是 XrTrackableMarkerDatabaseEntryANDROID 陣列的指標，每個陣列都包含要追蹤的標記設定。

有效用途 (隱含)

必須先啟用 XR_ANDROID_trackables_marker 擴充功能，才能使用 XrTrackableMarkerDatabaseANDROID
dictionary「必須」是有效的 XrTrackableMarkerDictionaryANDROID 值
如果 entryCount 不是 0，entries「必須」是指向 entryCount 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 代表標記邊緣的大小 (以公尺為單位)。如果執行階段支援標記大小估算，應用程式可以將此值設為零，系統會線上估算標記大小。如果這個值設為零，但執行階段不支援標記大小估算，則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

有效用途 (隱含)

必須先啟用 XR_ANDROID_trackables_marker 擴充功能，才能使用 XrTrackableMarkerDatabaseEntryANDROID

取得標記

xrGetTrackableMarkerANDROID 函式的定義如下：

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

參數說明

tracker 是要查詢的 XrTrackableTrackerANDROID。
getInfo 是 XrTrackableGetInfoANDROID，其中包含用於取得可追蹤標記的資訊。
markerOutput 是指向 XrTrackableMarkerANDROID 結構的指標，可追蹤標記會傳回至該結構。

如果 XrTrackableANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_MARKER_ANDROID，或 XrTrackableTrackerANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_MARKER_ANDROID，執行階段必須傳回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。

有效用途 (隱含)

必須先啟用 XR_ANDROID_trackables_marker 擴充功能，才能呼叫 xrGetTrackableMarkerANDROID
tracker「必須」是有效的 XrTrackableTrackerANDROID 控制代碼
getInfo「必須」是指向有效 XrTrackableGetInfoANDROID 結構的指標
markerOutput「必須」是指向 XrTrackableMarkerANDROID 結構的指標

傳回代碼

成功

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 是標記的 XrPosef，位於 XrTrackableGetInfoANDROID :: baseSpace。標記位於 XZ 平面，X 指向標記右側，Z 指向標記底部，Y 則從標記向外延伸，做為法線。
extents 是標記的 XrExtent2Df 維度。定界框的邊界位於以下點：centerPose +/- ( extents / 2)。

有效用途 (隱含)

必須先啟用 XR_ANDROID_trackables_marker 擴充功能，才能使用 XrTrackableMarkerANDROID
type「必須」為 XR_TYPE_TRACKABLE_MARKER_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
trackingState「必須」是有效的 XrTrackingStateANDROID 值
dictionary「必須」是有效的 XrTrackableMarkerDictionaryANDROID 值

取得可追蹤標記的程式碼範例

下列程式碼範例示範如何取得可追蹤的標記。

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));

新指令

xrGetTrackableMarkerANDROID

新結構

XrTrackableMarkerANDROID
XrTrackableMarkerDatabaseANDROID
XrTrackableMarkerDatabaseEntryANDROID
擴充 XrSystemProperties：
- XrSystemMarkerTrackingPropertiesANDROID
擴充 XrTrackableTrackerCreateInfoANDROID：
- XrTrackableMarkerConfigurationANDROID

新列舉常數

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)
- 初始擴充功能說明。