XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

709

Revision

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

XR_ANDROID_trackables

Статус прекращения поддержки

  • Устарело из-за расширения XR_EXT_spatial_marker_tracking

Дата последнего изменения

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

Обзор

Это расширение позволяет отслеживать физические QR-коды и декодировать данные QR-кодов.

Разрешения

В манифесте приложений для Android должно быть указано разрешение android.permission.SCENE_UNDERSTANDING_COARSE, поскольку это расширение зависит от XR_ANDROID_trackables и раскрывает геометрию среды. Разрешение android.permission.SCENE_UNDERSTANDING_COARSE считается опасным.

(уровень защиты: опасный)

Проверка возможностей системы

Структура XrSystemQrCodeTrackingPropertiesANDROID определяется следующим образом:

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • supportsQrCodeTracking – это XrBool32, указывающее, поддерживает ли текущая система отслеживание QR-кодов.
  • supportsQrCodeSizeEstimation – XrBool32, указывающее, предоставляет ли текущая система оценку размера QR-кода.
  • maxQrCodeCount – максимальное количество QR-кодов, которые можно отслеживать одновременно.

Приложение может проверить, способна ли система отслеживать QR-коды, расширив XrSystemProperties с помощью структуры XrSystemQrCodeTrackingPropertiesANDROID при вызове xrGetSystemProperties . Среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED для создания счетчика QR-кодов, если и только если supportsQrCodeTracking – это XR_FALSE .

Если среда выполнения поддерживает отслеживание QR-кодов, значение maxQrCodeCount должно быть не меньше 1. Если среда выполнения не поддерживает отслеживание QR-кодов, значение maxQrCodeCount должно быть равно 0.

Допустимое использование (неявное)

Отслеживание QR-кодов

Это расширение добавляет XR_TRACKABLE_TYPE_QR_CODE_ANDROID в XrTrackableTypeANDROID .

Приложение может создать XrTrackableTrackerANDROID, вызвав xrCreateTrackableTrackerANDROID и указав XR_TRACKABLE_TYPE_QR_CODE_ANDROID в качестве отслеживаемого типа в XrTrackableTrackerCreateInfoANDROID :: trackableType, чтобы отслеживать QR-коды.

Среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED, если XrTrackableTrackerCreateInfoANDROID :: trackableType – это XR_TRACKABLE_TYPE_QR_CODE_ANDROID, а XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking возвращает XR_FALSE через xrGetSystemProperties .

Структура XrTrackableQrCodeConfigurationANDROID определяется следующим образом:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    XrQrCodeTrackingModeANDROID    trackingMode;
    float                          qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • trackingMode – это XrQrCodeTrackingModeANDROID, указывающий нужный режим отслеживания.
  • qrCodeEdgeSize – размер стороны QR-кода в метрах. Если указан ноль, среда выполнения оценивает размер QR-кода онлайн.

Приложение должно задать действительную конфигурацию, добавив XrTrackableQrCodeConfigurationANDROID в следующую цепочку XrTrackableTrackerCreateInfoANDROID . В противном случае среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE .

Если среда выполнения поддерживает оценку размера QR-кода, приложение может установить для XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize значение 0.0, чтобы указать на использование оценки размера.

Если среда выполнения не поддерживает оценку размера QR-кода, приложение должно задать для XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize положительное значение. В противном случае среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE .

Среда выполнения должна фильтровать выходные данные из xrGetAllTrackablesANDROID, чтобы они соответствовали trackingMode . Если для XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize не задано значение 0.0, среда выполнения должна возвращать только QR-коды, соответствующие этому размеру. Если для XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize задано значение 0.0, среда выполнения должна возвращать все QR-коды с приблизительным размером.

Допустимое использование (неявное)

Перечисление XrQrCodeTrackingModeANDROID описывает поддерживаемые режимы отслеживания QR-кодов.

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM = 1000314000,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

Описания перечислений

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID – отслеживание динамических QR-кодов. Этот режим обеспечивает самую высокую точность и работает с движущимися и статичными QR-кодами, но при этом потребляет больше всего энергии.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID – отслеживание статических QR-кодов. Этот режим в основном используется для статических QR-кодов и позволяет снизить энергопотребление по сравнению с динамическим режимом.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM – этот режим следует использовать для статических QR-кодов. В отличие от статического режима, в этом режиме QR-код отслеживается только один раз, а затем положения отслеживаемых экземпляров обновляются исключительно на основе положения устройства. В результате отслеживание продолжается, даже если QR-код выходит за пределы контрольного кадра. Это позволяет минимизировать энергопотребление после отслеживания QR-кода. (Добавлено расширением XR_QCOM_trackables_qr_code_operations)

Получить QR-коды

Функция xrGetTrackableQrCodeANDROID определяется следующим образом:

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

Описание параметров

  • tracker – XrTrackableTrackerANDROID для запроса.
  • getInfo – это XrTrackableGetInfoANDROID с информацией, которая используется для получения отслеживаемого QR-кода.
  • qrCodeOutput – указатель на структуру XrTrackableQrCodeANDROID, в которой возвращается отслеживаемый QR-код.

Среда выполнения должна возвращать XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID, если отслеживаемый тип XrTrackableANDROID не равен XR_TRACKABLE_TYPE_QR_CODE_ANDROID или если отслеживаемый тип XrTrackableTrackerANDROID не равен XR_TRACKABLE_TYPE_QR_CODE_ANDROID .

Допустимое использование (неявное)

Коды возврата

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Структура 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 QR-кода.
  • lastUpdatedTime – XrTime последнего обновления QR-кода. Если значение lastUpdatedTime изменилось с момента последнего вызова, то могли измениться и все остальные поля.
  • centerPose – это XrPosef QR-кода, расположенного в XrTrackableGetInfoANDROID :: baseSpace . QR-код находится в плоскости XZ, где X указывает на правую сторону QR-кода, Z – на его нижнюю часть, а Y выходит из QR-кода как нормаль.
  • extents – размеры QR-кода XrExtent2Df. Границы рамки находятся в точках centerPose +/- ( extents / 2).
  • bufferCapacityInput – это функция buffer или 0 для получения нужной функции.
  • bufferCountOutput Если bufferCapacityInput – 0 , среда выполнения запишет требуемый размер буфера в bufferCountOutput . В противном случае в нем содержится общее количество элементов, записанных в buffer . Если данные QR-кода ещё не декодированы, среда выполнения должна установить для bufferCountOutput значение 0.
  • buffer – указатель на массив char для записи декодированных данных QR-кода. Если приложению не нужны декодированные данные QR-кода, оно может передать nullptr и пропустить второй вызов. Данные QR-кода возвращаются в виде строки UTF-8 с нулевым символом в конце.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Допустимое использование (неявное)

Пример кода для получения отслеживаемых QR-кодов

В примере кода ниже показано, как получить отслеживаемые QR-коды.

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, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    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));

Новые команды

Новые структуры

Новые перечисления

Новые константы перечисления

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Расширение XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Расширение XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Проблемы

История версий

  • Версия 1, 5 февраля 2025 г. (Левана Чен)

    • Начальное описание расширения.