XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

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

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

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

708

Revision

1

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

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

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

XR_ANDROID_trackables

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

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

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

2025-07-23

Статус IP-адреса

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

Авторы

Кристофер Дёр (Christopher Doer), Google
Диего Типальди (Diego Tipaldi), Google
Леван Чен (Levana Chen), Google
Джаред Финдер (Jared Finder), Google
Спенсер Квин (Spencer Quin), Google
Нихав Джайн (Nihav Jain), Google
Кен Маккей (Ken Mackay), Google
Дэниел Гуттенберг (Daniel Guttenberg), Qualcomm

Обзор

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

Расширение поддерживает известные типы маркеров, в частности ArUco и AprilTag. Это позволяет средам выполнения поддерживать оценку размера маркера.

Разрешения

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

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

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

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

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении. Дополнительную информацию о цепочке структур можно найти в описании расширяемой структуры ( XrSystemProperties).
  • supportsMarkerTracking – это XrBool32, указывающий, поддерживает ли текущая система отслеживание маркеров.
  • supportsMarkerSizeEstimation – это XrBool32, указывающий, предоставляет ли текущая система оценку размера маркера.
  • maxMarkerCount – максимальное количество маркеров, которые среда выполнения может отслеживать одновременно.

Приложение может проверить, способна ли система отслеживать маркеры. Для этого нужно расширить XrSystemProperties с помощью структуры XrSystemMarkerTrackingPropertiesANDROID при вызове xrGetSystemProperties. Среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED для создания трекера маркеров, только если supportsMarkerTracking – это XR_FALSE .

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

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

Маркеры отслеживания

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

Приложение создает XrTrackableTrackerANDROID, вызывая xrCreateTrackableTrackerANDROID и указывая XR_TRACKABLE_TYPE_MARKER_ANDROID в качестве отслеживаемого типа в XrTrackableTrackerCreateInfoANDROID :: trackableType, а также задавая действительную конфигурацию, добавляя XrTrackableMarkerConfigurationANDROID в следующую цепочку XrTrackableTrackerCreateInfoANDROID .

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

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

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • trackingMode – это XrTrackableMarkerTrackingModeANDROID, указывающий желаемый режим отслеживания.
  • databaseCount – это uint32_t, описывающий количество элементов в массиве databases.
  • databases – указатель на массив XrTrackableMarkerDatabaseANDROID , каждый из которых содержит нужные маркеры из заданного словаря для отслеживания.

Приложение должно задать действительную конфигурацию, добавив XrTrackableMarkerConfigurationANDROID в цепочку XrTrackableTrackerCreateInfoANDROID :: next при вызове xrCreateTrackableTrackerANDROID с XrTrackableTrackerCreateInfoANDROID :: trackableType, для которого задано значение XR_TRACKABLE_TYPE_MARKER_ANDROID . Если тип трекера задан, как указано выше, но структура конфигурации отсутствует или недействительна, среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE .

Если среда выполнения поддерживает оценку размера маркера, приложение может задать для XrTrackableMarkerDatabaseEntryANDROID :: edgeSize значение 0 в XrTrackableMarkerDatabaseANDROID :: entries, чтобы указать на использование оценки размера. В противном случае приложение должно задать для XrTrackableMarkerDatabaseEntryANDROID :: edgeSize положительное значение, или среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE .

Среда выполнения должна фильтровать выходные данные из xrGetAllTrackablesANDROID, чтобы они соответствовали trackingMode и XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

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

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

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

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

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID – отслеживание динамических маркеров. Этот режим обеспечивает самую высокую точность и работает как с движущимися, так и со статичными маркерами, но при этом потребляет больше всего энергии.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID – отслеживание статических маркеров. Этот режим в основном используется для маркеров, которые считаются статическими, что приводит к меньшему энергопотреблению по сравнению с динамическим режимом.

Структура XrTrackableMarkerDatabaseANDROID определяет словарь и соответствующие идентификаторы маркеров, которые нужно отслеживать.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

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

  • dictionary – это XrTrackableMarkerDictionaryANDROID, к которому относятся все entries.
  • entryCount – это uint32_t, описывающий количество элементов в массиве entries. Приложение может задать entryCount 0, чтобы отслеживать все маркеры в dictionary .
  • entries – указатель на массив XrTrackableMarkerDatabaseEntryANDROID , каждый элемент которого содержит конфигурацию маркера для отслеживания.

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

Перечисление XrTrackableMarkerDictionaryANDROID описывает поддерживаемые словари маркеров.

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

Структура XrTrackableMarkerDatabaseEntryANDROID настраивает один идентификатор маркера словаря.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

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

  • id – идентификатор маркера, указанный в словаре.
  • edgeSize – размер края маркера в метрах. Если среда выполнения поддерживает оценку размера маркера, приложение может установить нулевое значение, и размер маркера будет оцениваться онлайн. Если это значение равно нулю, но среда выполнения не поддерживает оценку размера маркера, среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE .

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

Получить маркеры

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

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

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

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

Среда выполнения должна возвращать XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID, если отслеживаемый тип XrTrackableANDROID не равен XR_TRACKABLE_TYPE_MARKER_ANDROID или если отслеживаемый тип XrTrackableTrackerANDROID не равен XR_TRACKABLE_TYPE_MARKER_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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • trackingState – XrTrackingStateANDROID маркера.
  • lastUpdatedTime – XrTime последнего обновления маркера.
  • dictionary – XrTrackableMarkerDictionaryANDROID маркера.
  • markerId – идентификатор маркера, указанный в словаре.
  • centerPose – это XrPosef маркера, расположенного в XrTrackableGetInfoANDROID :: baseSpace . Маркер лежит в плоскости XZ, где X указывает на правую сторону маркера, Z – на его нижнюю сторону, а Y выходит из маркера как нормаль.
  • extents – размеры маркера XrExtent2Df. Границы рамки находятся в точках centerPose +/- ( extents / 2).

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

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

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

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_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // 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
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

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

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

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

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

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

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

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

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

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Проблемы

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

  • Версия 1, 23 июля 2025 г. (Левана Чэнь)

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