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 .
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием XrSystemImageTrackingPropertiesANDROID. -
typeдолжен бытьXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур.
Создание баз данных
Приложение может создать дескриптор 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.
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием XrTrackableImageDatabaseEntryANDROID. -
typeдолжен бытьXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур. -
trackingModeдолжен быть допустимым значением XrTrackableImageTrackingModeANDROID. -
formatдолжен быть допустимым значением XrTrackableImageFormatANDROID -
bufferдолжен быть указателем на массив значенийbufferSizeтипаuint8_t - Параметр
bufferSizeдолжен быть больше0
Структура 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 .
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием функции XrTrackableImageDatabaseCreateInfoANDROID. -
typeдолжен бытьXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур. -
entriesдолжны представлять собой указатель на массив допустимых структур XrTrackableImageDatabaseEntryANDROID, содержащийentryCount - Параметр
entryCountдолжен быть больше0
Структура 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
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием XrCreateTrackableImageDatabaseCompletionANDROID. -
typeдолжен бытьXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур. -
futureResultдолжно быть допустимым значением XrResult. -
databaseдолжна быть допустимым дескриптором XrTrackableImageDatabaseANDROID.
Функция 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_ANDROID_trackables_imageнеобходимо включить перед вызовом функции xrCreateTrackableImageDatabaseCompleteANDROID. -
sessionдолжна быть действительным дескриптором XrSession. -
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используется идентификатор XrTrackableImageDatabaseANDROID .
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед вызовом функции xrDestroyTrackableImageDatabaseANDROID. -
databaseдолжна быть допустимым дескриптором XrTrackableImageDatabaseANDROID.
Безопасность резьбы
- Доступ к
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 для создания трекера.
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием XrTrackableImageConfigurationANDROID. -
typeдолжен бытьXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур. -
databasesдолжен быть указателем на массив допустимых дескрипторов XrTrackableImageDatabaseANDROID, содержащихdatabaseCount. - Параметр
databaseCountдолжен быть больше0
Перечисление 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);
Описание параметров
-
tracker— это идентификатор XrTrackableTrackerANDROID , в который нужно добавитьdatabase. -
database— это идентификатор XrTrackableImageDatabaseANDROID , который нужно добавить вtracker.
При добавлении объекта 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);
Описание параметров
-
tracker— это идентификатор XrTrackableTrackerANDROID , из которого нужно удалитьdatabase. -
database— это идентификатор XrTrackableImageDatabaseANDROID , который нужно удалить изtracker.
При удалении объекта 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);
Описание параметров
- Для запроса используется
trackerXrTrackableTrackerANDROID . -
getInfo— это объект XrTrackableGetInfoANDROID , содержащий информацию, необходимую для получения отслеживаемого QR-кода. -
trackable— это указатель на структуру XrTrackableImageANDROID , в которой возвращается отслеживаемое изображение.
В случае, если тип отслеживания объекта XrTrackableANDROID не равен XR_TRACKABLE_TYPE_IMAGE_ANDROID , или если тип отслеживания объекта XrTrackableTrackerANDROID не равен XR_TRACKABLE_TYPE_IMAGE_ANDROID , среда выполнения должна вернуть XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID .
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед вызовом функции xrGetTrackableImageANDROID. -
trackerдолжен быть действительным идентификатором XrTrackableTrackerANDROID. -
getInfoдолжна быть указателем на допустимую структуру XrTrackableGetInfoANDROID. -
trackableдолжен быть указателем на структуру XrTrackableImageANDROID.
Коды возврата
-
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).
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием XrTrackableImageANDROID. typeдолжен бытьXR_TYPE_TRACKABLE_IMAGE_ANDROIDnextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур.-
trackingStateдолжен быть допустимым значением XrTrackingStateANDROID. databaseдолжна быть допустимым дескриптором XrTrackableImageDatabaseANDROID.
Обработка сбоев
Приложение должно опрашивать событие XrEventDataImageTrackingLostANDROID с помощью xrPollEvent и не должно его игнорировать.
Структура XrEventDataImageTrackingLostANDROID определяется следующим образом:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
Описание участников
-
type— это XrStructureType данной структуры. -
nextравноNULLили указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены. -
timeXrTime
Получение события XrEventDataImageTrackingLostANDROID указывает на то, что отслеживание изображений завершилось с внутренней ошибкой, в результате которой существующие ресурсы стали недействительными. Приложение должно уничтожить все дескрипторы XrTrackableImageDatabaseANDROID и создать их заново, если оно хочет продолжить отслеживание изображений. Приложение также должно уничтожить все связанные с отслеживанием изображений дескрипторы XrTrackableTrackerANDROID и создать их заново, если оно хочет продолжить отслеживание изображений.
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageнеобходимо включить перед использованием XrEventDataImageTrackingLostANDROID. -
typeдолжен бытьXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур.
Пример кода для получения отслеживаемых изображений.
Приведенный ниже пример кода демонстрирует, как получить отслеживаемые изображения.
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;
}
}
}
Новые типы объектов
Новые команды
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Новые сооружения
- XrCreateTrackableImageDatabaseCompleteANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Расширение XrSystemProperties :
Новые перечисления
Новые константы перечислений
-
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 (Даниэль Гуттенберг)
- Первоначальное описание расширения.