XR_ANDROID_trackables_image
名称字符串
XR_ANDROID_trackables_image
扩展类型
实例扩展程序
已注册的扩展程序编号
710
修订版本
1
批准状态
未获批准
扩展程序和版本依赖项
XR_EXT_future
和
XR_ANDROID_trackables
上次修改日期
2025-04-08
IP 状态
没有已知的 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。
应用可以通过调用 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 数组,用于指定要使用哪些数据库来创建跟踪器。
应用必须通过向 XrTrackableTrackerCreateInfoANDROID 的 next 链添加 XrTrackableImageConfigurationANDROID 来设置有效配置。否则,运行时必须返回 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是要从中移除database的 XrTrackableTrackerANDROID 句柄。database是要从tracker中移除的 XrTrackableImageDatabaseANDROID 句柄。
当 XrTrackableImageDatabaseANDROID 从 XrTrackableTrackerANDROID 中移除时,该数据库的 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,其中包含了用于获取可跟踪二维码的信息。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 -
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 的database数组entries。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)
- 初始扩展程序说明。