XR_ANDROID_trackables_image

Строка имени

XR_ANDROID_trackables_image

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

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

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

710

Пересмотр

1

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

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

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

XR_EXT_future
и
XR_ANDROID_trackables

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

2025-04-08

Статус IP

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

Авторы

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

Обзор

Это расширение позволяет отслеживать плоские изображения в соответствии с заданными наборами входных эталонных изображений.

Разрешения

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

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

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

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

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

  • type — это XrStructureType данной структуры.
  • Значение next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены. Для получения более подробной информации о цепочке структур см. расширяемую структуру ( XrSystemProperties ).
  • supportsImageTracking — это тип данных XrBool32 указывающий, поддерживает ли текущая система функцию отслеживания изображений.
  • supportsPhysicalSizeEstimation — это тип данных XrBool32 , указывающий, поддерживает ли текущая система оценку размера изображения.
  • maxTrackedImageCount — это максимальное общее количество изображений, которые могут отслеживаться одновременно.
  • maxLoadedImageCount — это максимальное общее количество эталонных изображений, которые могут быть загружены во все базы данных.

Приложение может проверить, способна ли система отслеживать изображения, расширив структуру XrSystemProperties структурой XrSystemImageTrackingPropertiesANDROID при вызове функции xrGetSystemProperties . Среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED для создания средства отслеживания изображений только в том случае, если supportsImageTracking имеет значение XR_FALSE .

Если среда выполнения поддерживает отслеживание изображений, она должна поддерживать максимальное количество отслеживаемых изображений maxTrackedImageCount в любой момент времени.

Если среда выполнения поддерживает отслеживание изображений, она должна поддерживать maxLoadedImageCount позволяющее загружать изображения одновременно.

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

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

Создание баз данных

Приложение может создать дескриптор XrTrackableImageDatabaseANDROID , создав одну или несколько структур XrTrackableImageDatabaseEntryANDROID и передав их в функцию xrCreateTrackableImageDatabaseAsyncANDROID через структуру XrTrackableImageDatabaseCreateInfoANDROID .

При создании дескриптора XrTrackableImageDatabaseANDROID приложение должно предоставить как минимум один объект XrTrackableImageDatabaseEntryANDROID .

Объект XrTrackableImageDatabaseANDROID — это дескриптор, представляющий собой набор обработанных эталонных изображений, которые можно обнаружить и отслеживать в окружающей среде.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • trackingMode — это значение параметра XrTrackableImageTrackingModeANDROID , указывающее на желаемый режим отслеживания.
  • physicalWidth указывает ширину изображения в метрах. Если значение равно нулю, размер изображения будет оценен в режиме реального времени.
  • imageWidth указывает ширину изображения в пикселях.
  • imageHeight указывает высоту изображения в пикселях.
  • format представляет собой объект XrTrackableImageFormatANDROID, указывающий формат данных изображения в buffer .
  • bufferSize указывает длину buffer в байтах.
  • buffer — это буфер типа uint8_t , содержащий данные пикселей эталонного изображения. Содержимое buffer должно оставаться действительным в течение асинхронной операции создания базы данных, которая запускается функцией xrCreateTrackableImageDatabaseAsyncANDROID и завершается функцией xrCreateTrackableImageDatabaseCompleteANDROID .

Приложение может установить physicalWidth равным 0 для запроса онлайн-оценки размера, если XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation имеет значение XR_TRUE .

В случае, если bufferSize не соответствует ожидаемому размеру, рассчитанному на основе imageWidth , imageHeight и format записи, среда выполнения может вернуть XR_ERROR_VALIDATION_FAILURE из функции xrCreateTrackableImageDatabaseAsyncANDROID.

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

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • entryCount — это тип данных uint32_t , указывающий количество элементов в массиве entries .
  • entries представляет собой массив структур XrTrackableImageDatabaseEntryANDROID .

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

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

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • futureResult — это XrResult асинхронной операции.
  • database — это созданный дескриптор XrTrackableImageDatabaseANDROID .

Будущие коды возврата

Значения futureResult :

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

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

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

  • session — это дескриптор объекта XrSession, ранее созданного с помощью xrCreateSession .
  • createInfo — это указатель на структуру XrTrackableImageDatabaseCreateInfoANDROID .
  • future — это указатель на созданный объект XrFutureEXT .

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

  • Расширение XR_ANDROID_trackables_image необходимо включить перед вызовом функции xrCreateTrackableImageDatabaseAsyncANDROID.
  • session должна быть действительным дескриптором XrSession.
  • createInfo должна быть указателем на допустимую структуру XrTrackableImageDatabaseCreateInfoANDROID.
  • future должен быть указателем на значение XrFutureEXT

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

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

  • session — это дескриптор объекта XrSession, ранее созданного с помощью xrCreateSession .
  • future — это XrFutureEXT будущего, которое нужно завершить.
  • completion — это указатель на структуру `XrCreateTrackableImageDatabaseCompletionANDROID` , содержащую результат операции.

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

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

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

Безопасность резьбы

  • Доступ к database и любым дочерним элементам должен синхронизироваться извне.

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Изображения слежения

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

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

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

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • databaseCount — это тип данных uint32_t , указывающий количество элементов в databases
  • databases — это массив объектов XrTrackableImageDatabaseANDROID , который указывает базы данных, с помощью которых будет создан трекер.

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

Приложение должно предоставить как минимум одну структуру XrTrackableImageDatabaseANDROID для создания трекера.

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

Перечисление XrTrackableImageTrackingModeANDROID описывает поддерживаемые режимы отслеживания изображений.

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

Описание переписчиков

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID — Этот режим обеспечивает высочайшую точность и позволяет отслеживать движущиеся изображения с низкой задержкой. Он также отличается самым высоким энергопотреблением.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID — Этот режим следует использовать для изображений, которые заведомо являются статическими или полустатическими. Он обеспечивает меньшее энергопотребление по сравнению с динамическим режимом. При перемещении статического изображения обновление происходит с гораздо большей задержкой, чем при использовании динамического режима.

Перечисление XrTrackableImageFormatANDROID описывает поддерживаемые форматы изображений.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

Описание переписчиков

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID — формат изображения RGBA с 8 битами на канал для данных о цвете и прозрачности.

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

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

При добавлении объекта XrTrackableImageDatabaseANDROID к трекеру, эталонные изображения из этой базы данных должны учитываться для обнаружения и отслеживания в дополнение к любым другим базам данных, которые были добавлены ранее либо с помощью xrAddTrackableImageDatabaseANDROID , либо через структуру XrTrackableImageConfigurationANDROID при первоначальном создании трекера.

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

  • Расширение XR_ANDROID_trackables_image необходимо включить перед вызовом функции xrAddTrackableImageDatabaseANDROID.
  • tracker должен быть действительным идентификатором XrTrackableTrackerANDROID.
  • database должна быть допустимым дескриптором XrTrackableImageDatabaseANDROID.
  • И database , и tracker должны быть созданы, выделены или получены из одной и той же XrSession.

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

При удалении объекта XrTrackableImageDatabaseANDROID из объекта XrTrackableTrackerANDROID структуры XrTrackableImageDatabaseEntryANDROID этой базы данных больше не должны рассматриваться для обнаружения и отслеживания. Любые активно отслеживаемые записи этой базы данных больше не должны сообщаться. Удаленный дескриптор XrTrackableImageDatabaseANDROID не должен быть неявно уничтожен в рамках этой операции.

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

  • Расширение XR_ANDROID_trackables_image необходимо включить перед вызовом функции xrRemoveTrackableImageDatabaseANDROID.
  • tracker должен быть действительным идентификатором XrTrackableTrackerANDROID.
  • database должна быть допустимым дескриптором XrTrackableImageDatabaseANDROID.
  • И database , и tracker должны быть созданы, выделены или получены из одной и той же XrSession.

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Получение изображений

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

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

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

  • Для запроса используется tracker XrTrackableTrackerANDROID .
  • getInfo — это объект XrTrackableGetInfoANDROID , содержащий информацию, необходимую для получения отслеживаемого QR-кода.
  • trackable — это указатель на структуру XrTrackableImageANDROID , в которой возвращается отслеживаемое изображение.

В случае, если тип отслеживания объекта XrTrackableANDROID не равен XR_TRACKABLE_TYPE_IMAGE_ANDROID , или если тип отслеживания объекта XrTrackableTrackerANDROID не равен XR_TRACKABLE_TYPE_IMAGE_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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • trackingState — это значение XrTrackingStateANDROID для изображения.
  • lastUpdatedTime — это XrTime последнего обновления изображения.
  • database указан идентификатор XrTrackableImageDatabaseANDROID , с которого было отслежено это изображение.
  • databaseEntryIndex — это индекс, который отображается в массив XrTrackableImageDatabaseCreateInfoANDROID :: entries объекта database .
  • centerPose — это XrPosef изображения, расположенного в XrTrackableGetInfoANDROID :: baseSpace . Изображение находится в плоскости XZ, при этом X направлено вправо от изображения, а Z — вниз.
  • extents — это размеры изображения по XrExtent2Df . Граница ограничивающего прямоугольника определяется точками: centerPose +/- ( extents / 2).

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

Обработка сбоев

Приложение должно опрашивать событие XrEventDataImageTrackingLostANDROID с помощью xrPollEvent и не должно его игнорировать.

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • time XrTime

Получение события XrEventDataImageTrackingLostANDROID указывает на то, что отслеживание изображений завершилось с внутренней ошибкой, в результате которой существующие ресурсы стали недействительными. Приложение должно уничтожить все дескрипторы XrTrackableImageDatabaseANDROID и создать их заново, если оно хочет продолжить отслеживание изображений. Приложение также должно уничтожить все связанные с отслеживанием изображений дескрипторы XrTrackableTrackerANDROID и создать их заново, если оно хочет продолжить отслеживание изображений.

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

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

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

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

Пример кода для управления базами данных изображений во время выполнения.

Приведенный ниже пример кода демонстрирует, как изменить набор отслеживаемых изображений.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

Пример кода для реагирования на ошибки отслеживания изображения.

Приведенный ниже пример кода демонстрирует, как обрабатывать сбои путем опроса события XrEventDataImageTrackingLostANDROID .

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

Новые типы объектов

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

Новые сооружения

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

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

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • Расширение XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • Расширение XrResult :

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

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • Расширение XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

Проблемы

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

  • Редакция 1, 08.04.2025 (Даниэль Гуттенберг)

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