XR_ANDROID_trackables_qr_code

Строка имени

XR_ANDROID_trackables_qr_code

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

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

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

709

Пересмотр

1

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

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

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

XR_ANDROID_trackables

Состояние депрекции

  • Устарело в расширении XR_EXT_spatial_marker_tracking

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

2025-02-05

Статус IP

Известных претензий на интеллектуальную собственность нет.

Авторы

Кристофер Доер, Google
Левана Чен, Google
Джаред Финдер, Google
Спенсер Куин, Google
Нихав Джайн, Google
Диего Типальди, Google
Кен Маккей, Google
Даниэль Гуттенберг, 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-кодов.

Если функция XrTrackableTrackerCreateInfoANDROID :: trackableType имеет значение XR_TRACKABLE_TYPE_QR_CODE_ANDROID , а функция XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking возвращает значение XR_FALSE через xrGetSystemProperties , среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED .

Структура 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-код.

В случае, если тип отслеживаемого объекта XrTrackableANDROID не равен XR_TRACKABLE_TYPE_QR_CODE_ANDROID , среда выполнения должна вернуть XR_ERROR_MISMATCHING_TRACKABLE_TYPE_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, 05 февраля 2025 г. (Левана Чен)

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