XR_ANDROID_trackables_qr_code Расширение OpenXR

Имя Строка

XR_ANDROID_trackables_qr_code

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

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

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

460

Пересмотр

1

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

XR_ANDROID_trackables

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

2025-02-05

Статус IP

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

Авторы

Кристофер Доер, Google

Левана Чен, Google

Джаред Файндер, Google

Спенсер Куин, Google

Нихав Джайн, Google

Диего Типальди, Google

Кен Маккей, Google

Дэниел Гуттенберг, Qualcomm

Обзор

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

Проверить возможности системы

XrSystemQrCodeTrackingPropertiesANDROID

Структура XrSystemQrCodeTrackingPropertiesANDROID определяется как:

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint32_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 отслеживаемых QR-кодов в любой момент времени.

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

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

  • Расширение XR_ANDROID_trackables_qr_code должно быть включено перед использованием XrSystemQrCodeTrackingPropertiesANDROID
  • type должен быть XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next должен быть NULL или действительным указателем на следующую структуру в цепочке структур

Отслеживание 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

Структура XrTrackableQrCodeConfigurationANDROID определяется как:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const 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 чтобы указать на использование оценки размера. В противном случае приложение должно установить XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize равным положительному значению, иначе будет возвращено исключение XR_ERROR_VALIDATION_FAILURE .

Среда выполнения должна фильтровать выходные данные xrGetAllTrackablesANDROID для соответствия trackingMode и qrCodeEdgeSize .

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

  • Перед использованием XrTrackableQrCodeConfigurationANDROID необходимо включить расширение XR_ANDROID_trackables_qr_code
  • type должен быть XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next должен быть NULL или действительным указателем на следующую структуру в цепочке структур
  • trackingMode должен иметь допустимое значение XrQrCodeTrackingModeANDROID

XrQrCodeTrackingModeANDROID

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

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 | QR-код статичен и не перемещается. | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | QR-код динамичен и может перемещаться. |

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

xrGetTrackableQrCodeANDROID

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

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

  • Перед использованием XrTrackableQrCodeANDROID необходимо включить расширение XR_ANDROID_trackables_qr_code
  • type должен быть XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next должен быть NULL или действительным указателем на следующую структуру в цепочке структур
  • trackingState должно быть допустимым значением XrTrackingStateANDROID
  • Если bufferCapacityInput не равен 0 , buffer должен быть указателем на массив значений типа bufferCapacityInput

Пример кода для получения отслеживаемых 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);
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_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

Перечисление XrTrackableTypeANDROID расширено:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

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

  • XrQrCodeTrackingModeANDROID

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

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Новые функции

  • xrGetTrackableQrCodeANDROID

Проблемы

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

  • Редакция 1, 05 февраля 2025 г. (Левана Чен)
    • Первоначальное описание расширения.

OpenXR™ и логотип OpenXR являются товарными знаками компании Khronos Group Inc. и зарегистрированы в качестве товарных знаков в Китае, Европейском Союзе, Японии и Великобритании.