XR_ANDROID_trackables_image

名稱字串

XR_ANDROID_trackables_image

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

710

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_future

XR_ANDROID_trackables

上次修改日期

2025-04-08

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)

總覽

這項擴充功能可追蹤平面圖像,並以一組輸入參考圖像指定。

權限

Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_COARSE 權限,因為這項擴充功能會公開環境的幾何結構,並依附於 XR_ANDROID_trackables。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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。如要進一步瞭解結構體鏈結,請參閱擴充的結構體 ( XrSystemProperties)。
  • supportsImageTrackingXrBool32,用於指出目前的系統是否提供圖片追蹤功能。
  • supportsPhysicalSizeEstimationXrBool32,指出目前系統是否提供圖片大小估算值。
  • maxTrackedImageCount同時追蹤的圖片總數上限。
  • maxLoadedImageCount 是所有資料庫可載入的參考圖片總數上限。

應用程式可以在呼叫 xrGetSystemProperties 時,使用 XrSystemImageTrackingPropertiesANDROID 結構擴充 XrSystemProperties,檢查系統是否支援影像追蹤。如果 supportsImageTrackingXR_FALSE,執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED,才能建立圖片追蹤器。

如果執行階段支援圖像追蹤,則必須隨時支援 maxTrackedImageCount 追蹤的圖像。

如果執行階段支援圖片追蹤,則必須支援隨時載入圖片。maxLoadedImageCount

如果執行階段支援預估圖片大小,應用程式可以設定 XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0,指出大小預估的使用情形。否則,應用程式必須XrTrackableImageDatabaseEntryANDROID :: physicalWidth 設為正值,否則系統會傳回 XR_ERROR_VALIDATION_FAILURE

有效使用 (隱含)

  • XR_ANDROID_trackables_image 擴充功能必須先啟用,才能使用 XrSystemImageTrackingPropertiesANDROID
  • type 必須XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標

建立資料庫

應用程式可以建立一或多個 XrTrackableImageDatabaseEntryANDROID 結構體,並透過 XrTrackableImageDatabaseCreateInfoANDROID 結構體將這些結構體傳遞至 xrCreateTrackableImageDatabaseAsyncANDROID 函式,藉此建立 XrTrackableImageDatabaseANDROID 控制代碼。

建立 XrTrackableImageDatabaseANDROID 控制代碼時,應用程式必須提供至少一個 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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • trackingModeXrTrackableImageTrackingModeANDROID,表示追蹤的所需模式。
  • physicalWidth 表示圖片寬度 (以公尺為單位)。如果為零,系統會線上估算圖片大小。
  • imageWidth:以像素為單位表示圖片寬度。
  • imageHeight 表示圖片的高度 (以像素為單位)。
  • formatXrTrackableImageFormatANDROID,表示 buffer 中的圖像資料格式。
  • bufferSize 表示 buffer 的位元組長度。
  • buffer 是包含參照圖片像素資料的 uint8_t 緩衝區。buffer 的內容必須在資料庫建立非同步作業期間有效,這項作業是由 xrCreateTrackableImageDatabaseAsyncANDROID 啟動,並由 xrCreateTrackableImageDatabaseCompleteANDROID 完成。

如果 XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimationXR_TRUE,應用程式「可以」physicalWidth 設為 0,要求進行線上大小估算。

如果 bufferSize 不符合根據項目的 imageWidthimageHeightformat 預期的尺寸,執行階段「可能」會從 xrCreateTrackableImageDatabaseAsyncANDROID 傳回 XR_ERROR_VALIDATION_FAILURE

有效使用 (隱含)

XrTrackableImageDatabaseCreateInfoANDROID 結構體的定義如下:

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

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • entryCountuint32_t,指定 entries 陣列中的元素數量。
  • XrTrackableImageDatabaseEntryANDROID 結構體的陣列。entries

有效使用 (隱含)

  • 使用 XrTrackableImageDatabaseCreateInfoANDROID 前,必須先啟用 XR_ANDROID_trackables_image 擴充功能
  • type 必須XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • entries must 是有效 XrTrackableImageDatabaseEntryANDROID 結構陣列的指標entryCount
  • entryCount 參數必須大於 0

XrCreateTrackableImageDatabaseCompletionANDROID 結構體的定義如下:

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

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 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

追蹤圖片

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

應用程式可以呼叫 xrCreateTrackableTrackerANDROID 並在 XrTrackableTrackerCreateInfoANDROID :: trackableType 中指定 XR_TRACKABLE_TYPE_IMAGE_ANDROID 做為可追蹤類型,藉此建立 XrTrackableTrackerANDROID 來追蹤圖片。

如果 XrTrackableTrackerCreateInfoANDROID :: trackableTypeXR_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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • databaseCountuint32_t,可指定 databases 中的元素數量
  • databasesXrTrackableImageDatabaseANDROID 的陣列,指定要用來建立追蹤器的資料庫。

應用程式必須新增 XrTrackableImageConfigurationANDROIDXrTrackableTrackerCreateInfoANDROIDnext 鏈結,藉此設定有效設定。否則,執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE

應用程式必須提供至少一個 XrTrackableImageDatabaseANDROID 結構,才能建立追蹤器。

有效使用 (隱含)

  • 使用 XrTrackableImageConfigurationANDROID 前,必須先啟用 XR_ANDROID_trackables_image 擴充功能
  • type 必須XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • databases 必須是指向有效 XrTrackableImageDatabaseANDROID 控制代碼陣列的指標databaseCount
  • databaseCount 參數必須大於 0

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:RGBA 圖片格式,每個色版有 8 位元的顏色和透明度資料。

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

參數說明

XrTrackableTrackerANDROID 移除 XrTrackableImageDatabaseANDROID 時,必須停止偵測及追蹤該資料庫的 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;

成員說明

有效使用 (隱含)

失敗事件的處理

應用程式必須使用 xrPollEvent 輪詢 XrEventDataImageTrackingLostANDROID 事件,且不得忽略該事件。

XrEventDataImageTrackingLostANDROID 結構體的定義如下:

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

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • time XrTime

收到 XrEventDataImageTrackingLostANDROID 事件表示圖片追蹤發生內部錯誤,導致現有資源失效。應用程式必須銷毀所有 XrTrackableImageDatabaseANDROID 控制代碼,並重新建立這些控制代碼,才能繼續追蹤圖片。應用程式必須一併銷毀所有與圖像追蹤相關的 XrTrackableTrackerANDROID 控制代碼,並在想繼續追蹤圖像時重新建立。

有效使用 (隱含)

  • XR_ANDROID_trackables_image 擴充功能必須先啟用,才能使用 XrEventDataImageTrackingLostANDROID
  • type 必須XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標

取得可追蹤圖片的程式碼範例

下列範例程式碼說明如何取得可追蹤的圖片。

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)

    • 擴充功能說明。