XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

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

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

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

710

Revision

1

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

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

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

XR_EXT_future
и
XR_ANDROID_trackables

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

2025-04-08

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

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

Авторы

Кристофер Дёр (Christopher Doer), Google
Левана Чэнь (Levana Chen), Google
Джаред Финдер (Jared Finder), Google
Спенсер Куин (Spencer Quin), Google
Нихав Джайн (Nihav Jain), Google
Диего Типальди (Diego Tipaldi), Google
Дэниел Гуттенберг (Daniel Guttenberg), Qualcomm
Марк Вадаси (Mark Vadasi), Qualcomm
Маркус Биркнер (Markus Birkner), Qualcomm
Максимилиан Майер (Maximilian Mayer), 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 .

Среда выполнения может возвращать XR_ERROR_VALIDATION_FAILURE из xrCreateTrackableImageDatabaseAsyncANDROID, если bufferSize не соответствует ожидаемому размеру на основе imageWidth, imageHeight и format записи.

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

Структура 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);

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

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

  • Расширение 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, чтобы отслеживать изображения.

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

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

Среда выполнения должна возвращать XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID, если отслеживаемый тип XrTrackableANDROID не равен XR_TRACKABLE_TYPE_IMAGE_ANDROID или если отслеживаемый тип XrTrackableTrackerANDROID не равен XR_TRACKABLE_TYPE_IMAGE_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 – индекс, который сопоставляется с массивом entries объектов database в XrTrackableImageDatabaseCreateInfoANDROID.
  • 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 (Дэниел Гуттенберг)

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