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。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。如要進一步瞭解結構體鏈結,請參閱擴充的結構體 ( XrSystemProperties)。supportsImageTracking是XrBool32,用於指出目前的系統是否提供圖片追蹤功能。supportsPhysicalSizeEstimation是XrBool32,指出目前系統是否提供圖片大小估算值。maxTrackedImageCount是可同時追蹤的圖片總數上限。maxLoadedImageCount是所有資料庫可載入的參考圖片總數上限。
應用程式可以在呼叫 xrGetSystemProperties 時,使用 XrSystemImageTrackingPropertiesANDROID 結構擴充 XrSystemProperties,檢查系統是否支援影像追蹤。如果 supportsImageTracking 為 XR_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。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。trackingMode是 XrTrackableImageTrackingModeANDROID,表示追蹤的所需模式。physicalWidth表示圖片寬度 (以公尺為單位)。如果為零,系統會線上估算圖片大小。imageWidth:以像素為單位表示圖片寬度。imageHeight表示圖片的高度 (以像素為單位)。format是 XrTrackableImageFormatANDROID,表示buffer中的圖像資料格式。bufferSize表示buffer的位元組長度。buffer是包含參照圖片像素資料的uint8_t緩衝區。buffer的內容必須在資料庫建立非同步作業期間有效,這項作業是由 xrCreateTrackableImageDatabaseAsyncANDROID 啟動,並由 xrCreateTrackableImageDatabaseCompleteANDROID 完成。
如果 XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation 為 XR_TRUE,應用程式「可以」將 physicalWidth 設為 0,要求進行線上大小估算。
如果 bufferSize 不符合根據項目的 imageWidth、imageHeight 和 format 預期的尺寸,執行階段「可能」會從 xrCreateTrackableImageDatabaseAsyncANDROID 傳回 XR_ERROR_VALIDATION_FAILURE。
有效使用 (隱含)
-
XR_ANDROID_trackables_image擴充功能必須先啟用,才能使用 XrTrackableImageDatabaseEntryANDROID -
type必須為XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
trackingMode必須是有效的 XrTrackableImageTrackingModeANDROID 值 -
format必須是有效的 XrTrackableImageFormatANDROID 值 -
buffer必須是指向bufferSizeuint8_t值陣列的指標 -
bufferSize參數必須大於0
XrTrackableImageDatabaseCreateInfoANDROID 結構體的定義如下:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。entryCount是uint32_t,指定entries陣列中的元素數量。- 是 XrTrackableImageDatabaseEntryANDROID 結構體的陣列。
entries
有效使用 (隱含)
- 使用 XrTrackableImageDatabaseCreateInfoANDROID 前,必須先啟用
XR_ANDROID_trackables_image擴充功能 -
type必須為XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
entriesmust 是有效 XrTrackableImageDatabaseEntryANDROID 結構陣列的指標entryCount -
entryCount參數必須大於0
XrCreateTrackableImageDatabaseCompletionANDROID 結構體的定義如下:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。futureResult是非同步作業的 XrResult。database是建立的 XrTrackableImageDatabaseANDROID 控制代碼。
日後推出的退貨代碼
futureResult 值:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
有效使用 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能使用 XrCreateTrackableImageDatabaseCompletionANDROID -
type必須為XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
futureResult必須是有效的 XrResult 值 -
database必須是有效的 XrTrackableImageDatabaseANDROID 控制代碼
xrCreateTrackableImageDatabaseAsyncANDROID 函式定義如下:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
參數說明
session是先前使用 xrCreateSession 建立的 XrSession 控制代碼。createInfo是 XrTrackableImageDatabaseCreateInfoANDROID 結構的指標。future是所建立XrFutureEXT的指標。
有效使用 (隱含)
- 呼叫 xrCreateTrackableImageDatabaseAsyncANDROID 前,
XR_ANDROID_trackables_image擴充功能必須啟用 -
sessionmust be a valid XrSession handle -
createInfo必須是指向有效 XrTrackableImageDatabaseCreateInfoANDROID 結構體的指標 -
future必須是指向XrFutureEXT值的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrCreateTrackableImageDatabaseCompleteANDROID 函式定義如下:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
參數說明
session是先前使用 xrCreateSession 建立的 XrSession 控制代碼。future是要完成的XrFutureEXT。completion是 XrCreateTrackableImageDatabaseCompletionANDROID 結構的指標,內含作業結果。
有效使用 (隱含)
- 呼叫 xrCreateTrackableImageDatabaseCompleteANDROID 前,
XR_ANDROID_trackables_image擴充功能必須啟用 -
sessionmust be a valid XrSession handle -
completion必須是指向 XrCreateTrackableImageDatabaseCompletionANDROID 結構體的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrDestroyTrackableImageDatabaseANDROID 函式定義如下:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
參數說明
database是要銷毀的 XrTrackableImageDatabaseANDROID 控制代碼。
有效使用 (隱含)
- 呼叫 xrDestroyTrackableImageDatabaseANDROID 前,
XR_ANDROID_trackables_image擴充功能必須啟用 -
database必須是有效的 XrTrackableImageDatabaseANDROID 控制代碼
執行緒安全
- 對
database和任何子項控制代碼的存取權必須從外部同步處理
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
追蹤圖片
這項擴充功能會將 XR_TRACKABLE_TYPE_IMAGE_ANDROID 新增至 XrTrackableTypeANDROID。
應用程式可以呼叫 xrCreateTrackableTrackerANDROID 並在 XrTrackableTrackerCreateInfoANDROID :: trackableType 中指定 XR_TRACKABLE_TYPE_IMAGE_ANDROID 做為可追蹤類型,藉此建立 XrTrackableTrackerANDROID 來追蹤圖片。
如果 XrTrackableTrackerCreateInfoANDROID :: trackableType 為 XR_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。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。databaseCount是uint32_t,可指定databases中的元素數量databases是 XrTrackableImageDatabaseANDROID 的陣列,指定要用來建立追蹤器的資料庫。
應用程式必須新增 XrTrackableImageConfigurationANDROID 至 XrTrackableTrackerCreateInfoANDROID 的 next 鏈結,藉此設定有效設定。否則,執行階段必須傳回 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);
參數說明
tracker是要新增database的 XrTrackableTrackerANDROID 控制代碼。database是要新增至tracker的 XrTrackableImageDatabaseANDROID 控制代碼。
將 XrTrackableImageDatabaseANDROID 新增至追蹤器時,除了先前透過 xrAddTrackableImageDatabaseANDROID 或在最初建立追蹤器時,透過 XrTrackableImageConfigurationANDROID 結構新增的任何其他資料庫,系統必須將該資料庫的參考圖片納入偵測和追蹤範圍。
有效使用 (隱含)
- 呼叫 xrAddTrackableImageDatabaseANDROID 前,
XR_ANDROID_trackables_image擴充功能必須啟用 -
trackermust 為有效的 XrTrackableTrackerANDROID 控制代碼 -
database必須是有效的 XrTrackableImageDatabaseANDROID 控制代碼 -
database和tracker必須從同一個 XrSession 建立、分配或擷取
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrRemoveTrackableImageDatabaseANDROID 函式定義如下:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
參數說明
tracker是要移除database的 XrTrackableTrackerANDROID 控制代碼。database是要從tracker移除的 XrTrackableImageDatabaseANDROID 控制代碼。
從 XrTrackableTrackerANDROID 移除 XrTrackableImageDatabaseANDROID 時,必須停止偵測及追蹤該資料庫的 XrTrackableImageDatabaseEntryANDROID 結構。該資料庫中所有主動追蹤的項目都不得再回報。移除的 XrTrackableImageDatabaseANDROID 控制代碼不得在此作業中隱含地遭到破壞。
有效使用 (隱含)
- 呼叫 xrRemoveTrackableImageDatabaseANDROID 前,
XR_ANDROID_trackables_image擴充功能必須啟用 -
trackermust 為有效的 XrTrackableTrackerANDROID 控制代碼 -
database必須是有效的 XrTrackableImageDatabaseANDROID 控制代碼 -
database和tracker必須從同一個 XrSession 建立、分配或擷取
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
取得圖片
xrGetTrackableImageANDROID 函式定義如下:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
參數說明
tracker是要查詢的 XrTrackableTrackerANDROID。getInfo是 XrTrackableGetInfoANDROID,其中包含用於取得可追蹤 QR code 的資訊。trackable是 XrTrackableImageANDROID 結構的指標,可追蹤的圖片會傳回至該指標。
如果 XrTrackableANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_IMAGE_ANDROID,或 XrTrackableTrackerANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_IMAGE_ANDROID,則執行階段「必須」傳回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。
有效使用 (隱含)
-
XR_ANDROID_trackables_image擴充功能必須先啟用,才能呼叫 xrGetTrackableImageANDROID -
trackermust 為有效的 XrTrackableTrackerANDROID 控制代碼 -
getInfo必須是指向有效 XrTrackableGetInfoANDROID 結構體的指標 -
trackable必須是指向 XrTrackableImageANDROID 結構體的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。trackingState是圖片的 XrTrackingStateANDROID。lastUpdatedTime是映像檔上次更新的XrTime。database是追蹤這張圖片的 XrTrackableImageDatabaseANDROID 控制代碼。databaseEntryIndex是對應至 XrTrackableImageDatabaseCreateInfoANDROID ::entriesdatabase陣列的索引。centerPose是位於 XrTrackableGetInfoANDROID ::baseSpace的圖片 XrPosef。圖片位於 XZ 平面,X 指向圖片右側,Z 指向圖片底部。extents是圖片的 XrExtent2Df 尺寸。定界框的邊界位於點:centerPose+/- (extents/ 2)。
有效使用 (隱含)
-
XR_ANDROID_trackables_image擴充功能必須先啟用,才能使用 XrTrackableImageANDROID -
type必須為XR_TYPE_TRACKABLE_IMAGE_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
trackingState必須是有效的 XrTrackingStateANDROID 值 -
database必須是有效的 XrTrackableImageDatabaseANDROID 控制代碼
失敗事件的處理
應用程式必須使用 xrPollEvent 輪詢 XrEventDataImageTrackingLostANDROID 事件,且不得忽略該事件。
XrEventDataImageTrackingLostANDROID 結構體的定義如下:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。timeXrTime
收到 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;
}
}
}
新物件類型
新指令
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
新結構
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
新列舉
新增列舉常數
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_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_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
-
XR_TRACKABLE_TYPE_IMAGE_ANDROID
問題
版本記錄
修訂版本 1,2025 年 4 月 8 日 (Daniel Guttenberg)
- 擴充功能說明。