XR_ANDROID_trackables_marker

Строка имени

XR_ANDROID_trackables_marker

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

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

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

708

Пересмотр

1

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

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

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

XR_ANDROID_trackables

Состояние деморализации

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

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

2025-07-23

Статус IP

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

Авторы

Кристофер Доер, Google
Диего Типальди, Google
Левана Чен, Google
Джаред Финдер, Google
Спенсер Куин, Google
Нихав Джайн, Google
Кен Маккей, Google
Даниэль Гуттенберг, Qualcomm

Обзор

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

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

Разрешения

В манифесте 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 .

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

Структура 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 , в которой возвращается отслеживаемый маркер.

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

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