XR_EXT_spatial_image_tracking
名称字符串
XR_EXT_spatial_image_tracking
扩展程序类型
实例扩展程序
已注册的扩展程序编号
783
修订版本
1
批准状态
未批准
扩展程序和版本依赖项
XR_EXT_spatial_entity
创作贡献者
Daniel Guttenberg,Qualcomm
Nihav Jain,Google
Jared Finder,Google
Zhipeng Liu,字节跳动
概览
此扩展程序为 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 启动的异步操作。
在 xrCreateSpatialImageTrackingDatabaseAsyncEXT 调用完成后,运行时不得访问 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 输入数组为此调用提供的任何 XrSpatialReferenceImagePlaneEXT :: buffer 指针。应用可以在 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是一个 XrSpatialImageTrackingDatabaseEXT,使用 xrCreateSpatialImageTrackingDatabaseAsyncEXT ::createInfo中的数据和配置创建。
未来返回代码
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 句柄和底层资源。
应用可以在调用 xrDestroySpatialContextEXT 之前调用 xrDestroySpatialImageTrackingDatabaseEXT 函数。运行时不得再报告由此销毁的 XrSpatialImageTrackingDatabaseEXT 管理的图片。运行时必须继续报告由其他数据库管理的映像。
运行时必须确保 xrCreateSpatialDiscoverySnapshotCompleteEXT 返回的发现快照不包含与已销毁或无效的 XrSpatialImageTrackingDatabaseEXT 句柄相关的图片,即使该句柄是在应用调用 xrCreateSpatialDiscoverySnapshotAsyncEXT 之后销毁的。鉴于空间快照中的数据不可变,应用应在销毁 database 之前销毁所有已创建的 XrSpatialSnapshotEXT 句柄,否则应用在使用 xrQuerySpatialComponentDataEXT 时可能会收到无效的 XrSpatialImageTrackingDatabaseEXT 句柄。
应用可以调用 xrDestroySpatialContextEXT 函数来释放 XrSpatialContextEXT 句柄,然后再销毁创建 XrSpatialContextEXT 时使用的任何 XrSpatialImageTrackingDatabaseEXT 句柄。当 XrSpatialContextEXT 被销毁时,运行时不得隐式销毁这些 XrSpatialImageTrackingDatabaseEXT 句柄。
通过独立管理 XrSpatialContextEXT 和 XrSpatialImageTrackingDatabaseEXT 的生命周期,应用可以重复使用之前创建的 XrSpatialImageTrackingDatabaseEXT 句柄,而无需重新执行成本高昂的创建过程。
例如,销毁 XrSpatialContextEXT,然后使用相同的 XrSpatialImageTrackingDatabaseEXT 重新创建另一个 XrSpatialContextEXT,即可暂停和恢复图片跟踪,而无需执行其他初始化过程。
有效用法(隐式)
- 必须先启用
XR_EXT_spatial_image_tracking扩展程序,然后才能调用 xrDestroySpatialImageTrackingDatabaseEXT -
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 启用的扩展程序的格式。
有效用法(隐式)
- 必须先启用
XR_EXT_spatial_image_tracking扩展程序,然后才能调用 xrEnumerateSpatialReferenceImageFormatsEXT -
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 结构。
如果 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT 未由 xrEnumerateSpatialCapabilityFeaturesEXT 针对 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_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 枚举,则对于应用未在任何适用的 next 链中提供任何 XrSpatialImageSizeEXT 结构的图片,运行时必须自动提供图片大小。
为了让运行时能够自动准确地生成图片尺寸,可能需要某些设备功能和前提条件,例如立体摄像头、经过精确校准的摄像头外在和内在参数。
如果 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT 未由 xrEnumerateSpatialCapabilityFeaturesEXT 枚举,则应用必须将 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 时,如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中传入了 XrSpatialCapabilityConfigurationImageTrackingEXT 结构,运行时必须启用图像跟踪。
XrSpatialCapabilityConfigurationImageTrackingEXT 结构使应用能够发现 imageTrackingDatabases 中由 XrSpatialImageTrackingDatabaseEXT 句柄表示的参考图片。
如果 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 未由 xrEnumerateSpatialCapabilitiesEXT 枚举,则运行时必须返回 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 :: planes 数组中为 XrSpatialReferenceImageEXT :: format 的每个颜色通道提供一个 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必须是指向imageCount个 XrSpatialImage2DDataEXT 结构数组的指针 -
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 年 4 月 22 日(Daniel Guttenberg,Qualcomm)
- 初始扩展程序说明