XR_EXT_spatial_image_tracking
Name String
XR_EXT_spatial_image_tracking
擴充功能類型
執行個體擴充功能
擴充功能註冊編號
783
修訂版本
1
批准狀態
未批准
擴充功能和版本依附元件
XR_EXT_spatial_entity
著作人
Daniel Guttenberg,Qualcomm
Nihav Jain,Google
Jared Finder,Google
Zhipeng Liu,ByteDance
總覽
這項擴充功能可為 XR_EXT_spatial_entity 擴充功能提供圖片追蹤功能。可讓應用程式根據一組輸入的參考圖像,偵測及追蹤特定的平面圖像。
追蹤的圖片會以空間實體表示,並包含下列元件:
XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXTXR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
應用程式通常會以下列模式使用空間圖像追蹤擴充功能:
- 應用程式會先根據一組預先載入的參考圖像資料,建立一或多個 XrSpatialImageTrackingDatabaseEXT 控制代碼。
- 接著,應用程式會根據先前建立的 XrSpatialImageTrackingDatabaseEXT 控制代碼,建立 XrSpatialContextEXT 控制代碼。
- 接著,應用程式會釋出參考圖像資料,減少記憶體用量。
- 應用程式會根據空間實體存取模式,探索及查詢圖片。
- 應用程式可以載入其他參考圖像組合,並建立額外的 XrSpatialImageTrackingDatabaseEXT,然後從中建立 XrSpatialContextEXT,在執行階段動態擴充可偵測和追蹤的圖像組合。
- 應用程式可以刪除 XrSpatialImageTrackingDatabaseEXT 控制代碼,在執行階段動態減少可偵測及追蹤的圖片。
- 應用程式可以刪除 XrSpatialContextEXT 控制代碼,在執行階段動態減少可偵測和追蹤的圖片。
執行階段支援
執行階段必須使用 xrEnumerateSpatialCapabilitiesEXT 列出下列功能,宣告支援圖像追蹤功能:
XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT
設定
如要啟用平面圖片偵測和追蹤功能,應用程式可以在呼叫 xrCreateSpatialContextAsyncEXT 函式時,在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中傳遞 XrSpatialCapabilityConfigurationImageTrackingEXT 結構,並在每個 XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases 中傳遞 XrSpatialImageTrackingDatabaseEXT 結構陣列。
建立輸入圖片集
如要指定要偵測及追蹤的參考圖像,應用程式必須建立至少一組輸入參考圖像。一組輸入參考圖像由 XrSpatialImageTrackingDatabaseEXT 控制代碼表示,且至少包含一張圖像。
XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)
XrSpatialImageTrackingDatabaseEXT 控制代碼代表用於探索及更新使用者環境中部分空間圖片的資源。應用程式可以使用這個控制代碼,透過這個擴充功能中的其他函式探索及更新空間圖像。
建立空間圖像追蹤資料庫
xrCreateSpatialImageTrackingDatabaseAsyncEXT 函式的定義如下:
XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
XrSession session,
const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
XrFutureEXT* future);
參數說明
session是 XrSession,空間圖片追蹤資料庫會在這個工作階段中啟用。createInfo是 XrSpatialImageTrackingDatabaseCreateInfoEXT,用於指定空間圖像追蹤資料庫參數。future是指向XrFutureEXT的指標。
應用程式可以使用 xrCreateSpatialImageTrackingDatabaseAsyncEXT 函式建立 XrSpatialImageTrackingDatabaseEXT 控制代碼,並使用 createInfo 設定圖片追蹤資料庫的輸入參考圖像集。
如果任何輸入參考圖像的 XrSpatialReferenceImageEXT :: format 未由 xrEnumerateSpatialReferenceImageFormatsEXT 列舉,執行階段必須傳回 XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT。
如果無法根據 XrSpatialReferenceImageEXT 的參考圖像中繼資料,評估任何輸入參考圖像的 XrSpatialReferenceImageEXT :: planes 陣列,執行階段必須傳回 XR_ERROR_SPATIAL_IMAGE_INVALID_EXT。
如果任何輸入參考圖像的 XrSpatialReferenceImageEXT :: planes 陣列提供的平面數量,與 XrSpatialReferenceImageEXT :: format 的色彩通道數量不完全相同,執行階段必須傳回 XR_ERROR_SPATIAL_IMAGE_INVALID_EXT。
如果執行階段強制執行權限系統,控管應用程式對圖片追蹤功能的存取權,則在未授予應用程式這些權限時,執行階段必須傳回 XR_ERROR_PERMISSION_INSUFFICIENT。
這個函式會啟動非同步作業,並建立對應的 XrFutureEXT,可與 xrPollFutureEXT 和相關函式搭配使用。這個函式的傳回值只會指出參數是否可接受排定非同步作業。對應的完成函式為 xrCreateSpatialImageTrackingDatabaseCompleteEXT,當這個函式的 Future 處於 READY 狀態時,即可使用這個函式,並由該函式在完成結構 XrCreateSpatialImageTrackingDatabaseCompletionEXT 中填入輸出內容。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能呼叫 xrCreateSpatialImageTrackingDatabaseAsyncEXT -
session「必須」是有效的 XrSession 控制代碼 -
createInfo「必須」指向有效的 XrSpatialImageTrackingDatabaseCreateInfoEXT 結構 -
future「必須」是指向XrFutureEXT值的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_PERMISSION_INSUFFICIENTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXTXR_ERROR_SPATIAL_IMAGE_INVALID_EXTXR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXTXR_ERROR_VALIDATION_FAILURE
XrSpatialImageTrackingDatabaseCreateInfoEXT 結構定義如下:
typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
XrStructureType type;
const void* next;
uint32_t spatialReferenceImageCount;
const XrSpatialReferenceImageEXT* spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;
成員說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。spatialReferenceImageCount是spatialReferenceImages陣列中的元素數量。spatialReferenceImages是 XrSpatialReferenceImageEXT 的陣列。
XrSpatialImageTrackingDatabaseCreateInfoEXT 結構說明建立 XrSpatialImageTrackingDatabaseEXT 控制代碼的資訊。
每個 XrSpatialImageTrackingDatabaseEXT 都必須在 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 陣列中,使用至少一個 XrSpatialReferenceImageEXT 建立。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialImageTrackingDatabaseCreateInfoEXT -
type「必須」為XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標。另請參閱:XrSpatialImageSizeEXT、XrSpatialImageStaticOptimizationEXT -
spatialReferenceImages「必須」是指向spatialReferenceImageCount個有效 XrSpatialReferenceImageEXT 結構陣列的指標 -
spatialReferenceImageCount參數必須大於0
xrCreateSpatialImageTrackingDatabaseCompleteEXT 函式的定義如下:
XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
XrSession session,
XrFutureEXT future,
XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);
參數說明
session是先前傳遞至 xrCreateSpatialContextAsyncEXT ::session的 XrSession。future是從 xrCreateSpatialContextAsyncEXT 接收的XrFutureEXT。completion是 XrCreateSpatialImageTrackingDatabaseCompletionEXT 的指標。
xrCreateSpatialImageTrackingDatabaseCompleteEXT 會完成由 xrCreateSpatialImageTrackingDatabaseAsyncEXT 啟動的非同步作業。
執行階段不得存取任何 XrSpatialReferenceImagePlaneEXT :: buffer 指標,這些指標是由 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 輸入陣列提供,用於此 xrCreateSpatialImageTrackingDatabaseAsyncEXT 呼叫完成後。xrCreateSpatialImageTrackingDatabaseAsyncEXT 完成後,應用程式可以釋出任何 XrSpatialReferenceImagePlaneEXT :: buffer 資料,減少記憶體用量。
如果 future 未處於就緒狀態,執行階段必須傳回 XR_ERROR_FUTURE_PENDING_EXT。如果 future 已完成或取消,執行階段必須傳回 XR_ERROR_FUTURE_INVALID_EXT。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能呼叫 xrCreateSpatialImageTrackingDatabaseCompleteEXT -
session「必須」是有效的 XrSession 控制代碼 -
completion「必須」是指向 XrCreateSpatialImageTrackingDatabaseCompletionEXT 結構的指標
傳回代碼
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
XrCreateSpatialImageTrackingDatabaseCompletionEXT 結構定義如下:
typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
XrStructureType type;
void* next;
XrResult futureResult;
XrSpatialImageTrackingDatabaseEXT database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;
成員說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。futureResult是空間圖片追蹤資料庫建立作業的 XrResult。database是使用 xrCreateSpatialImageTrackingDatabaseAsyncEXT ::createInfo中的資料和設定建立的 XrSpatialImageTrackingDatabaseEXT。
未來退貨代碼
futureResult 值:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXTXR_ERROR_SPATIAL_IMAGE_INVALID_EXT
如果 futureResult 是成功代碼,database 必須是有效的控制代碼。如果 database 有效,則僅在 xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session 的生命週期內有效,或直到應用程式使用 xrDestroySpatialImageTrackingDatabaseEXT 刪除 database 為止,以先發生者為準。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrCreateSpatialImageTrackingDatabaseCompletionEXT -
type「必須」為XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
futureResult「必須」是有效的 XrResult 值 -
database「必須」是有效的 XrSpatialImageTrackingDatabaseEXT 控制代碼
刪除空間圖片追蹤資料庫
xrDestroySpatialImageTrackingDatabaseEXT 函式的定義如下:
XrResult xrDestroySpatialImageTrackingDatabaseEXT(
XrSpatialImageTrackingDatabaseEXT database);
參數說明
database是先前由 xrCreateSpatialImageTrackingDatabaseAsyncEXT 建立的 XrSpatialImageTrackingDatabaseEXT。
應用程式可以呼叫 xrDestroySpatialImageTrackingDatabaseEXT 函式,在完成空間圖片探索和更新工作後,釋出 database 控制代碼和基礎資源。
應用程式可以先呼叫 xrDestroySpatialImageTrackingDatabaseEXT 函式,再呼叫 xrDestroySpatialContextEXT。執行階段不得再回報由這個已刪除的 XrSpatialImageTrackingDatabaseEXT 管理的圖片。執行階段必須繼續回報其他資料庫管理的映像檔。
執行階段必須確保 xrCreateSpatialDiscoverySnapshotCompleteEXT 傳回的探索快照不含與已刪除或無效 XrSpatialImageTrackingDatabaseEXT 控制代碼相關的圖片,即使控制代碼是在應用程式呼叫 xrCreateSpatialDiscoverySnapshotAsyncEXT 後刪除也一樣。由於空間快照中的資料不可變更,應用程式應先刪除所有已建立的 XrSpatialSnapshotEXT 控制代碼,再刪除 database,否則應用程式在使用 xrQuerySpatialComponentDataEXT 時,可能會收到無效的 XrSpatialImageTrackingDatabaseEXT 控制代碼。
應用程式可以呼叫 xrDestroySpatialContextEXT 函式,釋出 XrSpatialContextEXT 控制代碼,然後再刪除建立 XrSpatialContextEXT 時使用的任何 XrSpatialImageTrackingDatabaseEXT 控制代碼。XrSpatialContextEXT 刪除時,執行階段不得隱含刪除這些 XrSpatialImageTrackingDatabaseEXT 控制代碼。
獨立管理 XrSpatialContextEXT 和 XrSpatialImageTrackingDatabaseEXT 的生命週期,可讓應用程式重複使用先前建立的 XrSpatialImageTrackingDatabaseEXT 控制代碼,不必重新執行耗費資源的建立程序。
舉例來說,如果先刪除 XrSpatialContextEXT,再使用相同的 XrSpatialImageTrackingDatabaseEXT 重新建立另一個 XrSpatialContextEXT,就能暫停及繼續追蹤圖片,不必執行其他初始化程序。
有效用途 (隱含)
- 呼叫 xrDestroySpatialImageTrackingDatabaseEXT 之前,必須啟用
XR_EXT_spatial_image_tracking擴充功能 -
database「必須」是有效的 XrSpatialImageTrackingDatabaseEXT 控制代碼
執行緒安全
- 存取
database和任何子項控制代碼時,必須從外部同步
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
支援的輸入圖片格式
應用程式應呼叫 xrEnumerateSpatialReferenceImageFormatsEXT,取得支援的輸入參考圖像格式清單。
xrEnumerateSpatialReferenceImageFormatsEXT 函式的定義如下:
XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
XrInstance instance,
XrSystemId systemId,
XrSpatialCapabilityEXT capability,
uint32_t formatCapacityInput,
uint32_t* formatCountOutput,
XrSpatialReferenceImageFormatEXT* formats);
參數說明
instance是 XrInstance 的控制代碼。systemId是要列舉輸入參考圖像格式的XrSystemId。capability是 XrSpatialCapabilityEXT,系統會列舉輸入參考圖像格式。formatCapacityInput是formats陣列的容量,或 0 表示要求擷取所需容量。formatCountOutput是格式數量,或formatCapacityInput不足時所需的容量。formats是 XrSpatialReferenceImageFormatEXT 的陣列。如果formatCapacityInput為 0,則可以是NULL。- 如要進一步瞭解如何擷取必要的
formats大小,請參閱「緩衝區大小參數」一節。
應用程式可以使用 xrEnumerateSpatialReferenceImageFormatsEXT,列舉特定 XrSystemId 針對特定 XrSpatialCapabilityEXT 支援的輸入參考圖像格式清單。
執行階段「不得」列舉未針對 instance 啟用的擴充功能格式。
有效用途 (隱含)
- 呼叫 xrEnumerateSpatialReferenceImageFormatsEXT 之前,必須啟用
XR_EXT_spatial_image_tracking擴充功能 -
instance「必須」是有效的 XrInstance 控制代碼 -
capability「必須」是有效的 XrSpatialCapabilityEXT 值 -
formatCountOutput「必須」是指向uint32_t值的指標 - 如果
formatCapacityInput不是0,formats必須是指向formatCapacityInputXrSpatialReferenceImageFormatEXT 值陣列的指標
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
如需任何擴充功能支援的所有參考圖像格式完整清單,請參閱 XrSpatialReferenceImageFormatEXT。
typedef enum XrSpatialReferenceImageFormatEXT {
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;
XrSpatialReferenceImageFormatEXT 列舉會識別執行階段「可能」支援的輸入參考圖像格式。
必須至少支援 XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT 值和 XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT 值。
列舉值的意義如下:
列舉說明
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT:RGBA 緩衝區。格式不保證記憶體中像素資料的版面配置。您必須使用對應 XrSpatialReferenceImagePlaneEXT 結構提供的中繼資料,存取像素。每個像素色彩通道的大小為 8 位元,因此每個像素的大小為 32 位元。XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT:RGB 緩衝區。格式不保證記憶體中像素資料的版面配置。您必須使用對應 XrSpatialReferenceImagePlaneEXT 結構提供的中繼資料,存取像素。每個像素色彩通道的大小為 8 位元,因此每個像素的大小為 24 位元。XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT:採用 4:2:0 模式色度子取樣的 YUV 緩衝區。格式不保證記憶體中像素資料的版面配置。您必須使用對應 XrSpatialReferenceImagePlaneEXT 結構提供的中繼資料,存取像素。每個解碼的 RGB 像素色彩通道大小為 8 位元,因此每個像素的大小為 24 位元。
立體圖像追蹤設定
這個擴充功能提供選用結構,應用程式可以用來設定圖片追蹤功能。
靜態圖片最佳化
XrSpatialImageStaticOptimizationEXT 結構定義如下:
typedef struct XrSpatialImageStaticOptimizationEXT {
XrStructureType type;
const void* next;
XrBool32 optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;
成員說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。optimizeForStaticImage是XrBool32,用於指出圖片是否移動。XR_TRUE值表示圖片不會移動。
如果 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT 是由 xrEnumerateSpatialCapabilityFeaturesEXT 列舉,用於 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 功能,則應用程式可以將 XrSpatialImageStaticOptimizationEXT 鏈結至 XrSpatialImageTrackingDatabaseCreateInfoEXT :: next 鏈結,或 XrSpatialReferenceImageEXT :: next。
如果應用程式將 XrSpatialImageStaticOptimizationEXT 鏈結至 XrSpatialImageTrackingDatabaseCreateInfoEXT 結構,且 optimizeForStaticImage 設為 XR_TRUE,則執行階段必須假設該 XrSpatialImageTrackingDatabaseEXT 的所有圖片都是靜態。因此,如果 optimizeForStaticImage 設為 XR_FALSE,執行階段必須假設該 XrSpatialImageTrackingDatabaseEXT 的所有圖片都不是靜態。
如果應用程式將 XrSpatialImageStaticOptimizationEXT 鏈結至 XrSpatialReferenceImageEXT 結構,且 optimizeForStaticImage 設為 XR_TRUE,執行階段必須假設這個參考圖像為靜態。同樣地,如果 optimizeForStaticImage 設為 XR_FALSE,執行階段「必須」假設這個參考圖像並非靜態。將 XrSpatialImageStaticOptimizationEXT 結構鏈結至 XrSpatialReferenceImageEXT 結構,優先順序高於鏈結至 XrSpatialImageTrackingDatabaseCreateInfoEXT 結構。
如果 xrEnumerateSpatialCapabilityFeaturesEXT 未針對 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 功能列舉 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT,且應用程式將 XrSpatialImageStaticOptimizationEXT 結構鏈結至任何適用的下一個鏈結,則執行階段必須從 xrCreateSpatialImageTrackingDatabaseAsyncEXT 傳回 XR_ERROR_VALIDATION_FAILURE。
這可能會讓執行階段產生更準確的姿勢和大小。
這可能會讓執行階段降低耗電量。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialImageStaticOptimizationEXT -
type「必須」為XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標
參考圖像寬度
XrSpatialImageSizeEXT 結構定義如下:
typedef struct XrSpatialImageSizeEXT {
XrStructureType type;
const void* next;
float physicalWidth;
} XrSpatialImageSizeEXT;
成員說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。physicalWidth是float值,代表要設定的實體寬度 (公尺)。
如果 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT 是由 xrEnumerateSpatialCapabilityFeaturesEXT 列舉,用於 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 功能,應用程式可以將 XrSpatialImageSizeEXT 鏈結至 XrSpatialImageTrackingDatabaseCreateInfoEXT :: next 或 XrSpatialReferenceImageEXT :: next。
如果應用程式將 XrSpatialImageSizeEXT 鏈結至 XrSpatialImageTrackingDatabaseCreateInfoEXT 結構,執行階段必須假設該 XrSpatialImageTrackingDatabaseEXT 的所有圖片寬度為 physicalWidth 公尺,高度則根據 XrSpatialReferenceImageEXT :: width 和 XrSpatialReferenceImageEXT :: height 隱含提供的顯示比例。
如果應用程式將 XrSpatialImageSizeEXT 鏈結至 XrSpatialReferenceImageEXT 結構,執行階段必須假設此參考圖像的寬度為 physicalWidth 公尺,高度則根據 XrSpatialReferenceImageEXT :: width 和 XrSpatialReferenceImageEXT :: height 隱含提供的顯示比例。將 XrSpatialImageSizeEXT 結構鏈結至 XrSpatialReferenceImageEXT 結構,優先順序高於鏈結至 XrSpatialImageTrackingDatabaseCreateInfoEXT 結構。
這可能會讓執行階段傳回更準確的姿勢和大小。
執行階段必須列舉 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT 或 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT,或兩者皆列舉。
如果 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT 是由 xrEnumerateSpatialCapabilityFeaturesEXT 列舉,則執行階段必須自動為應用程式未提供任何 XrSpatialImageSizeEXT 結構的圖片提供圖片大小,做為任何適用後續鏈結的一部分。
為確保執行階段能自動準確產生圖片大小,可能需要特定裝置功能和先決條件,例如立體相機、準確校正的相機外在和內在參數。
如果 xrEnumerateSpatialCapabilityFeaturesEXT 未列舉 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT,應用程式必須將 XrSpatialImageSizeEXT 結構連結至適用的下一個鏈結,讓所有圖片都有明確的大小,否則執行階段必須從 xrCreateSpatialImageTrackingDatabaseAsyncEXT 傳回 XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialImageSizeEXT -
type「必須」為XR_TYPE_SPATIAL_IMAGE_SIZE_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標
XrSpatialCapabilityConfigurationImageTrackingEXT 結構定義如下:
typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
uint32_t enabledComponentCount;
const XrSpatialComponentTypeEXT* enabledComponents;
uint32_t imageTrackingDatabaseCount;
const XrSpatialImageTrackingDatabaseEXT* imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;
成員說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。capability是 XrSpatialCapabilityEXT,且「必須」為XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT。enabledComponentCount是uint32_t,用於指定enabledComponents中的元素數量。enabledComponents是 XrSpatialComponentTypeEXT 陣列,用於指定要為這項功能啟用的元件。imageTrackingDatabaseCount是unint32_t,用於指定imageTrackingDatabases中的元素數量。imageTrackingDatabases是 XrSpatialImageTrackingDatabaseEXT 控制代碼的陣列,用於指定要為空間情境啟用的圖片追蹤資料庫。
如果支援圖片追蹤,且在呼叫 xrCreateSpatialContextAsyncEXT 時,XrSpatialCapabilityConfigurationImageTrackingEXT 結構傳入 XrSpatialContextCreateInfoEXT :: capabilityConfigs,則執行階段必須啟用圖片追蹤。
XrSpatialCapabilityConfigurationImageTrackingEXT 結構可讓應用程式探索 imageTrackingDatabases 中 XrSpatialImageTrackingDatabaseEXT 控制代碼代表的參考圖像。
如果 xrEnumerateSpatialCapabilitiesEXT 未列舉 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT,執行階段「必須」傳回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialCapabilityConfigurationImageTrackingEXT -
type「必須」為XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
capability「必須」是有效的 XrSpatialCapabilityEXT 值 -
enabledComponents「必須」指向包含enabledComponentCount個有效 XrSpatialComponentTypeEXT 值的陣列 -
imageTrackingDatabases「必須」指向imageTrackingDatabaseCount個有效 XrSpatialImageTrackingDatabaseEXT 控制代碼的陣列 -
enabledComponentCount參數必須大於0 -
imageTrackingDatabaseCount參數必須大於0
空間參考圖像
XrSpatialReferenceImagePlaneEXT 結構定義如下:
typedef struct XrSpatialReferenceImagePlaneEXT {
uint32_t bufferSize;
uint8_t* buffer;
uint32_t rowStride;
uint32_t pixelStride;
} XrSpatialReferenceImagePlaneEXT;
參數說明
bufferSize是buffer陣列的大小。buffer是代表平面資料的uint8_t資料陣列。rowStride是連續像素資料列兩個起始位置之間的位元組距離。pixelStride是兩個連續像素之間的位元組距離。
執行階段「必須」根據 rowStride 和 pixelStride 參數提供的模式存取 buffer。
應用程式必須設定 rowStride 和 pixelStride,讓執行階段只擷取這個 XrSpatialReferenceImagePlaneEXT 的有效像素。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialReferenceImagePlaneEXT -
buffer「必須」是指向bufferSizeuint8_t值陣列的指標 -
bufferSize參數必須大於0
XrSpatialReferenceImageEXT 結構定義如下:
typedef struct XrSpatialReferenceImageEXT {
XrStructureType type;
const void* next;
uint32_t width;
uint32_t height;
XrSpatialReferenceImageFormatEXT format;
uint32_t planeCount;
const XrSpatialReferenceImagePlaneEXT* planes;
} XrSpatialReferenceImageEXT;
參數說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。width是參考圖像的像素寬度。height是參考圖像的像素高度。format是代表圖片格式的 XrSpatialReferenceImageFormatEXT。planeCount是planes陣列中的元素數量。planes是 XrSpatialReferenceImagePlaneEXT 結構的陣列,代表圖片資料的平面。
應用程式可以建立一或多個 XrSpatialReferenceImageEXT 結構,每個結構代表一個輸入參考圖像,在建立 XrSpatialImageTrackingDatabaseEXT 控制代碼時,透過 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 傳遞至 xrCreateSpatialImageTrackingDatabaseAsyncEXT 函式。
應用程式必須以由左至右、由上至下的像素順序提供 XrSpatialReferenceImagePlaneEXT :: buffer 資料。
應用程式必須在 XrSpatialReferenceImageEXT :: format 的每個色彩通道,為 XrSpatialReferenceImageEXT :: planes 陣列提供 XrSpatialReferenceImagePlaneEXT 結構。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialReferenceImageEXT -
type「必須」為XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標。另請參閱:XrSpatialAnnotationQuadReferenceANDROID、XrSpatialImageSizeEXT、XrSpatialImageStaticOptimizationEXT -
format「必須」是有效的 XrSpatialReferenceImageFormatEXT 值 -
planes「必須」指向由planeCount個有效 XrSpatialReferenceImagePlaneEXT 結構組成的陣列 -
planeCount參數必須大於0
保證元件
支援 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 的執行階段「必須」提供下列空間元件,做為這些功能探索到的所有實體的保證元件,且必須在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉這些元件:
XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXTXR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
2D 圖片元件
用於查詢資料的元件清單結構
XrSpatialComponentImage2DListEXT 結構定義如下:
typedef struct XrSpatialComponentImage2DListEXT {
XrStructureType type;
const void* next;
uint32_t imageCount;
XrSpatialImage2DDataEXT* images;
} XrSpatialComponentImage2DListEXT;
參數說明
type是這個結構的 XrStructureType。next是NULL,或指向結構鏈中下一個結構的指標。imageCount是images陣列中的元素數量。images是 XrSpatialImage2DDataEXT 陣列。
如果 XrSpatialComponentImage2DListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。
如果 imageCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialComponentImage2DListEXT -
type「必須」為XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
images必須是指向imageCountXrSpatialImage2DDataEXT 結構陣列的指標 -
imageCount參數必須大於0
元件資料
XrSpatialImage2DDataEXT 結構定義如下:
typedef struct XrSpatialImage2DDataEXT {
XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase;
uint32_t referenceImageIndex;
} XrSpatialImage2DDataEXT;
參數說明
imageTrackingDatabase是偵測或追蹤圖片的 XrSpatialImageTrackingDatabaseEXT。referenceImageIndex是對應至 XrSpatialImageTrackingDatabaseCreateInfoEXT ::spatialReferenceImages陣列的索引,該陣列包含用於建立imageTrackingDatabase的輸入參考圖像。
應用程式可以使用 imageTrackingDatabase,找出先前建立的哪個 XrSpatialImageTrackingDatabaseEXT 包含這個 XrSpatialImage2DDataEXT 結構的參考圖像。對於該 XrSpatialImageTrackingDatabaseEXT,應用程式可以使用 referenceImageIndex 識別此 XrSpatialImage2DDataEXT 結構的 XrSpatialReferenceImageEXT,方法是將其與 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 陣列的輸入順序進行比對。
由所有有效資料庫定義的參考圖像集不應包含重複圖像。加入重複圖片可能會導致探索或追蹤行為不佳,例如傳回不一致或多個索引。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_image_tracking擴充功能,才能使用 XrSpatialImage2DDataEXT -
imageTrackingDatabase「必須」是有效的 XrSpatialImageTrackingDatabaseEXT 控制代碼
設定
如果 XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT 列舉在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中,代表某項功能,應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值,啟用該功能。這個元件不需要任何特殊設定,即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。
有界 2D 元件
有界 2D 元件會提供空間圖片的中心和範圍,由所在實體代表。如要進一步瞭解有界 2D 元件,請參閱「有界 2D」。
範例程式碼
探索空間圖像和查詢元件資料
以下程式碼範例說明如何探索圖像追蹤功能的空間實體,並查詢其元件資料。
XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized
uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
// Image tracking not supported
}
XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
// The image2d component is not supported
}
uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));
// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};
// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);
uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
// The desired format is not supported
}
// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
do {
// sleep(1);
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
} while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};
// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;
XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
uint32_t imgSize; // preloaded interleaved RGBA buffer size
uint8_t* img; // preloaded interleaved RGBA buffer data
// interleaved RGBA buffer memory layout and buffer positions
// first row of pixels
// img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
// R0 | G0 | B0 | A0 | R1 | G1 | ...
// second row of pixels
// img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
// R640 | G640 | B640 | A640 | R641 | ...
XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];
for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
}
XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
spatialReferenceImage.width = 640;
spatialReferenceImage.height = 480;
spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
spatialReferenceImage.planeCount = 4;
spatialReferenceImage.planes = spatialReferenceImagePlanes;
referenceImageIdentifiers.emplace_back("MyReferenceImage");
// Helper function to append to the next chain
XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
appendTo->next = toAppend;
appendTo = toAppend;
};
XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
imageSize.physicalWidth = 0.1f;
if (!supportsAutomaticScaleEstimation) {
if (supportsFixedSizeImages) {
appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
}
}
XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
imageStaticOptimization.optimizeForStaticImage = XR_TRUE;
if (supportsStaticImages) {
appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
}
XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;
XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));
waitUntilReady(createImageTrackingDatabaseFuture);
XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
// Error, image tracking database creation failed
}
imageTrackingDatabase = imageTrackingCompletion.database;
}
XrSpatialContextEXT spatialContext{};
{
const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
};
// Configure the image tracking capability for the spatial context
XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;
std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));
XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));
waitUntilReady(createContextFuture);
XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
// Error, spatial context creation failed
}
spatialContext = completion.spatialContext;
}
auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
// We want to look for entities that have the following components
std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
snapshotCreateInfo.componentTypes = snapshotComponents.data();
XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));
waitUntilReady(discoveryFuture);
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
completionInfo.baseSpace = localSpace;
completionInfo.time = time;
completionInfo.future = discoveryFuture;
XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
if (completion.futureResult == XR_SUCCESS) {
// Query for the bounded2d component data
XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypes = componentsToQuery;
XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));
std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();
queryResult.entityStateCapacityInput = entityStates.size();
queryResult.entityStates = entityStates.data();
std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
boundsList.boundCount = bounded2d.size();
boundsList.bounds = bounded2d.data();
queryResult.next = &boundsList;
std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
imagesList.imageCount = image2d.size();
imagesList.images = image2d.data();
queryResult.next = &imagesList;
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));
for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.
// Access bounded2d[i] for image bounds
}
}
CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
}
};
while (1) {
// For every frame in frame loop
XrFrameState frameState; // Previously returned from xrWaitFrame
const XrTime time = frameState.predictedDisplayTime;
// Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
// Discover spatial entities for the context that we received the "discovery
// recommended" event for
discoverSpatialEntities(eventdata.spatialContext, time);
break;
}
}
}
// Finish frame loop
}
CHK_XR(xrDestroySpatialContextEXT(spatialContext));
// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));
新物件類型
新指令
- xrCreateSpatialImageTrackingDatabaseAsyncEXT
- xrCreateSpatialImageTrackingDatabaseCompleteEXT
- xrDestroySpatialImageTrackingDatabaseEXT
- xrEnumerateSpatialReferenceImageFormatsEXT
新結構
- XrCreateSpatialImageTrackingDatabaseCompletionEXT
- XrSpatialCapabilityConfigurationImageTrackingEXT
- XrSpatialImage2DDataEXT
- XrSpatialImageTrackingDatabaseCreateInfoEXT
- XrSpatialReferenceImageEXT
- XrSpatialReferenceImagePlaneEXT
擴充 XrSpatialReferenceImageEXT、XrSpatialImageTrackingDatabaseCreateInfoEXT:
新列舉
新列舉常數
XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAMEXR_EXT_spatial_image_tracking_SPEC_VERSION擴充 XrObjectType:
XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT
擴充 XrResult:
XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXTXR_ERROR_SPATIAL_IMAGE_INVALID_EXTXR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
-
XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT
擴充 XrSpatialCapabilityFeatureEXT:
XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXTXR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXTXR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT
-
XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
擴充 XrStructureType:
XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXTXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXTXR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXTXR_TYPE_SPATIAL_IMAGE_SIZE_EXTXR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXTXR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXTXR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT
問題
版本記錄
修訂版本 1,2025-04-22 (Daniel Guttenberg,Qualcomm)
- 初始擴充功能說明