名称字符串
XR_ANDROID_trackables_qr_code
扩展程序类型
实例扩展
已注册的扩展程序数量
460
修订版本
1
扩展程序和版本依赖项
上次修改日期
2025-02-05
IP 状态
没有已知的知识产权主张。
创作贡献者
Christopher Doer，Google
Levana Chen，Google
Jared Finder，Google
Spencer Quin，Google
Nihav Jain，Google
Diego Tipaldi，Google
Ken Mackay，Google
Daniel Guttenberg，Qualcomm
概览
此扩展程序可实现实体二维码跟踪和二维码数据解码。
检查系统功能
XrSystemQrCodeTrackingPropertiesANDROID
XrSystemQrCodeTrackingPropertiesANDROID 结构的定义如下：
typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsQrCodeTracking;
XrBool32 supportsQrCodeSizeEstimation;
uint32_t maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;
会员说明
type是此结构的XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义此类结构。supportsQrCodeTracking是一个XrBool32，用于指示当前系统是否提供二维码跟踪功能。supportsQrCodeSizeEstimation是一个XrBool32，用于指示当前系统是否提供二维码大小估计。maxQrCodeCount是可同时跟踪的二维码总数上限。
应用可以在调用 xrGetSystemProperties 时通过使用 XrSystemQrCodeTrackingPropertiesANDROID 结构扩展 XrSystemProperties 来检查系统是否支持二维码跟踪。当且仅当 supportsQrCodeTracking 为 XR_FALSE 时，运行时必须针对二维码跟踪器创建返回 XR_ERROR_FEATURE_UNSUPPORTED。
如果运行时支持二维码跟踪，则必须支持在任何给定时间跟踪二维码。maxQrCodeCount
如果运行时支持二维码大小估计，应用可以设置 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 来指示大小估计的使用情况。否则，应用必须将 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 设置为正值，否则将返回 XR_ERROR_VALIDATION_FAILURE。
有效使用情况（隐式）
- 必须先启用
XR_ANDROID_trackables_qr_code扩展程序，然后才能使用XrSystemQrCodeTrackingPropertiesANDROID type必须为XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROIDnext必须为NULL或指向结构链中下一个结构的有效指针
跟踪二维码
此扩展程序会向 XrTrackableTypeANDROID 添加 XR_TRACKABLE_TYPE_QR_CODE_ANDROID。
应用可以通过调用 xrCreateTrackableTrackerANDROID 并在 XrTrackableTrackerCreateInfoANDROID::trackableType 中指定 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 作为可跟踪类型来创建 XrTrackableTrackerANDROID，以跟踪 QR 码。
如果 XrTrackableTrackerCreateInfoANDROID::trackableType 为 XR_TRACKABLE_TYPE_QR_CODE_ANDROID 且 XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking 通过 xrGetSystemProperties 返回 XR_FALSE，则运行时必须返回 XR_ERROR_FEATURE_UNSUPPORTED。
XrTrackableQrCodeConfigurationANDROID
XrTrackableQrCodeConfigurationANDROID 结构的定义如下：
typedef struct XrTrackableQrCodeConfigurationANDROID {
XrStructureType type;
const void* next;
XrQrCodeTrackingModeANDROID trackingMode;
float qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;
会员说明
type是此结构的XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义此类结构。trackingMode是一个XrQrCodeTrackingModeANDROID，用于指示所需的跟踪模式。qrCodeEdgeSize表示二维码边缘的大小（以米为单位）。 如果为零，系统将在线估计二维码大小。
应用必须通过向下一个 XrTrackableTrackerCreateInfoANDROID 链添加 XrTrackableQrCodeConfigurationANDROID 来设置有效配置。
否则，运行时必须返回 XR_ERROR_VALIDATION_FAILURE。
如果运行时支持二维码大小估计，应用可以将 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 设置为 0，以指示使用大小估计。
否则，应用必须将 XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 设置为正值，否则将返回 XR_ERROR_VALIDATION_FAILURE。
运行时必须过滤 xrGetAllTrackablesANDROID 的输出，以匹配 trackingMode 和 qrCodeEdgeSize。
有效使用情况（隐式）
- 必须先启用
XR_ANDROID_trackables_qr_code扩展程序，然后才能使用XrTrackableQrCodeConfigurationANDROID type必须为XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROIDnext必须为NULL或指向结构链中下一个结构的有效指针trackingMode必须是有效的XrQrCodeTrackingModeANDROID值
XrQrCodeTrackingModeANDROID
XrQrCodeTrackingModeANDROID 枚举描述了二维码支持的跟踪模式。
typedef enum XrQrCodeTrackingModeANDROID {
XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 0,
XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;
| 枚举 | 说明 XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID'
| XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | 二维码是动态的，可能会移动。 |
获取二维码
xrGetTrackableQrCodeANDROID
xrGetTrackableQrCodeANDROID 函数的定义如下：
XrResult xrGetTrackableQrCodeANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableQrCodeANDROID* qrCodeOutput);
参数说明
tracker是要查询的XrTrackableTrackerANDROID。getInfo是包含用于获取可追踪二维码的信息的XrTrackableGetInfoANDROID。qrCodeOutput是指向XrTrackableQrCodeANDROID结构的指针，用于返回可跟踪的二维码。
如果 XrTrackableANDROID 的可跟踪类型不是 XR_TRACKABLE_TYPE_QR_CODE_ANDROID，或者 XrTrackableTrackerANDROID 的可跟踪类型不是 XR_TRACKABLE_TYPE_QR_CODE_ANDROID，则运行时必须返回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。
有效使用情况（隐式）
- 在调用
xrGetTrackableQrCodeANDROID之前，必须启用XR_ANDROID_trackables_qr_code扩展程序。 tracker必须是有效的XrTrackableTrackerANDROID标识名getInfo必须是指向有效XrTrackableGetInfoANDROID结构的指针qrCodeOutput必须是指向XrTrackableQrCodeANDROID结构的指针
XrTrackableQrCodeANDROID
XrTrackableQrCodeANDROID 结构的定义如下：
typedef struct XrTrackableQrCodeANDROID {
XrStructureType type;
void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrPosef centerPose;
XrExtent2Df extents;
uint32_t bufferCapacityInput;
uint32_t bufferCountOutput;
char* buffer;
} XrTrackableQrCodeANDROID;
会员说明
type是此结构的XrStructureType。next是NULL或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义此类结构。trackingState是二维码的XrTrackingStateANDROID。lastUpdatedTime是二维码上次更新的XrTime。centerPose是位于XrTrackableGetInfoANDROID::baseSpace中的二维码的XrPosef。 二维码位于 XZ 平面内，其中 X 指向二维码的右侧，Z 指向二维码的底部。extents是二维码的XrExtent2Df维度。 边界框的边界位于以下点：centerPose+/- (extents/ 2)。bufferCapacityInput是buffer的功能，或0用于检索所需的功能。bufferCountOutput如果bufferCapacityInput为0，运行时会将所需的缓冲区大小写入bufferCountOutput。否则，它包含写入buffer的元素总数。buffer是一个指向char数组的指针，用于写入解码后的二维码数据。 应用可以传递nullptr来确定所需的缓冲区大小，或者确定是否请求解码二维码数据。QR 码数据以 null 终止的 UTF-8 字符串形式返回。- 如需详细了解如何检索所需的
buffer大小，请参阅缓冲区大小参数部分。
有效使用情况（隐式）
- 必须先启用
XR_ANDROID_trackables_qr_code扩展程序，然后才能使用XrTrackableQrCodeANDROID type必须为XR_TYPE_TRACKABLE_QR_CODE_ANDROIDnext必须为NULL或指向结构链中下一个结构的有效指针trackingState必须是有效的XrTrackingStateANDROID值- 如果
bufferCapacityInput不为0，则buffer必须是指向bufferCapacityInputchar 值数组的指针
用于获取可跟踪二维码的示例代码
以下示例代码演示了如何获取可追踪的二维码。
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // 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
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty =
{.type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID, .next = nullptr};
XrSystemProperties systemProperties = {.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &qrCodeProperty};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
// QR Code tracking is not supported.
return;
}
// Create a trackable tracker for QR Code tracking.
// If the runtime does not support size estimation, configures QR Code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration =
{.type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
.next = nullptr,
.trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
.qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f};
XrTrackableTrackerCreateInfoANDROID createInfo =
{.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &configuration,
.trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
// Handle permission requests.
}
CHK_XR(res);
// Get QR Codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
qrCodes[i].next = nullptr;
qrCodes[i].bufferCountOutput = 0;
XrTrackableGetInfoANDROID getInfo = {.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackables.at(i),
.baseSpace = appSpace,
.time = updateTime};
CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
if (qrCodes[i].bufferCountOutput > 0) {
// Allocate the buffer if it is not already allocated.
if (qrCodes[i].bufferCapacityInput == 0) {
qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
}
}
}
// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(qrCodeTracker));
新的枚举常量
XrStructureType 枚举已扩展为：
XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_QR_CODE_ANDROID
XrTrackableTypeANDROID 枚举已扩展为：
XR_TRACKABLE_TYPE_QR_CODE_ANDROID
新枚举
XrQrCodeTrackingModeANDROID
新结构
XrSystemQrCodeTrackingPropertiesANDROIDXrTrackableQrCodeConfigurationANDROIDXrTrackableQrCodeANDROID
新函数
xrGetTrackableQrCodeANDROID
问题
版本历史记录
- 修订版 1，2025-02-05（Levana Chen）
- 初始扩展程序说明。
OpenXR™ 和 OpenXR 徽标是 The Khronos Group Inc. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。