XR_ANDROID_trackables_image
Name String
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,或指向結構鏈中下一個結構的有效指標
建立資料庫
應用程式可以建立 XrTrackableImageDatabaseANDROID 控制代碼,方法是建立一或多個 XrTrackableImageDatabaseEntryANDROID 結構,並透過 XrTrackableImageDatabaseCreateInfoANDROID 結構傳遞至 xrCreateTrackableImageDatabaseAsyncANDROID 函式。
建立 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陣列中的元素數量。entries是 XrTrackableImageDatabaseEntryANDROID 結構的陣列。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能使用 XrTrackableImageDatabaseCreateInfoANDROID -
type「必須」為XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
entries「必須」是指向entryCount個有效 XrTrackableImageDatabaseEntryANDROID 結構陣列的指標 -
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的指標。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能呼叫 xrCreateTrackableImageDatabaseAsyncANDROID -
session「必須」是有效的 XrSession 控制代碼 -
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 結構的指標,其中包含作業結果。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能呼叫 xrCreateTrackableImageDatabaseCompleteANDROID -
session「必須」是有效的 XrSession 控制代碼 -
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 控制代碼。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能呼叫 xrDestroyTrackableImageDatabaseANDROID -
database「必須」是有效的 XrTrackableImageDatabaseANDROID 控制代碼
執行緒安全
- 存取
database和任何子項控制代碼時,必須從外部同步
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
追蹤圖片
這項擴充功能會將 XR_TRACKABLE_TYPE_IMAGE_ANDROID 新增至 XrTrackableTypeANDROID。
應用程式可以建立 XrTrackableTrackerANDROID,方法是呼叫 xrCreateTrackableTrackerANDROID,並在 XrTrackableTrackerCreateInfoANDROID :: trackableType 中指定 XR_TRACKABLE_TYPE_IMAGE_ANDROID 做為可追蹤類型,以追蹤圖片。
如果 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 結構,才能建立追蹤器。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能使用 XrTrackableImageConfigurationANDROID -
type「必須」為XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
databases「必須」指向由databaseCount個有效 XrTrackableImageDatabaseANDROID 控制代碼組成的陣列 -
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 結構新增的其他資料庫。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能呼叫 xrAddTrackableImageDatabaseANDROID -
tracker「必須」是有效的 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是 XrTrackableTrackerANDROID 控制代碼,用於移除database。database是要從tracker移除的 XrTrackableImageDatabaseANDROID 控制代碼。
從 XrTrackableTrackerANDROID 移除 XrTrackableImageDatabaseANDROID 時,不得再將該資料庫的 XrTrackableImageDatabaseEntryANDROID 結構用於偵測和追蹤。不得再回報該資料庫中任何主動追蹤的項目。移除的 XrTrackableImageDatabaseANDROID 控制代碼不得在此作業中隱含刪除。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_trackables_image擴充功能,才能呼叫 xrRemoveTrackableImageDatabaseANDROID -
tracker「必須」是有效的 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。
有效用途 (隱含)
- 呼叫 xrGetTrackableImageANDROID 前,必須啟用
XR_ANDROID_trackables_image擴充功能 -
tracker「必須」是有效的 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 ::entries陣列database的索引。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-04-08 (Daniel Guttenberg)
- 初始擴充功能說明。