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.
Допустимое использование (неявное)
- Расширение
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 .
Среда выполнения может возвращать XR_ERROR_VALIDATION_FAILURE из xrCreateTrackableImageDatabaseAsyncANDROID, если bufferSize не соответствует ожидаемому размеру на основе imageWidth, imageHeight и format записи.
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageдолжно быть включено до использования XrTrackableImageDatabaseEntryANDROID. -
typeдолжно бытьXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextдолжно бытьNULLили действительным указателем на следующую структуру в цепочке структур. -
trackingModeдолжно быть действительным значением XrTrackableImageTrackingModeANDROID. -
formatдолжно быть допустимым значением XrTrackableImageFormatANDROID. -
bufferдолжен быть указателем на массив значенийbufferSizeuint8_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должен быть указателем на массив изentryCountдопустимых структур XrTrackableImageDatabaseEntryANDROID. - Значение параметра
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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Функция xrDestroyTrackableImageDatabaseANDROID определяется следующим образом:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Описание параметров
database– дескриптор XrTrackableImageDatabaseANDROID, который нужно удалить.
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageдолжно быть включено до вызова xrDestroyTrackableImageDatabaseANDROID. -
databaseдолжен быть действительным дескриптором XrTrackableImageDatabaseANDROID.
Потокобезопасность
- Доступ к
databaseи любым дочерним дескрипторам должен быть синхронизирован извне.
Коды возврата
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_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, чтобы создать трекер.
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageдолжно быть включено до использования XrTrackableImageConfigurationANDROID. -
typeдолжно бытьXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextдолжно бытьNULLили действительным указателем на следующую структуру в цепочке структур. -
databasesдолжен быть указателем на массив изdatabaseCountдействительных дескрипторов XrTrackableImageDatabaseANDROID. - Значение параметра
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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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_ANDROID_trackables_imageдолжно быть включено до вызова xrGetTrackableImageANDROID. -
trackerдолжен быть действительным дескриптором XrTrackableTrackerANDROID. -
getInfoдолжен быть указателем на действительную структуру XrTrackableGetInfoANDROID. -
trackableдолжен быть указателем на структуру XrTrackableImageANDROID.
Коды возврата
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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).
Допустимое использование (неявное)
- Расширение
XR_ANDROID_trackables_imageдолжно быть включено до использования XrTrackableImageANDROID. -
typeдолжно бытьXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextдолжно быть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
Новые структуры
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Расширение XrSystemProperties :
Новые перечисления
Новые константы перечисления
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_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_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
Расширение XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Проблемы
История версий
Версия 1, 08.04.2025 (Дэниел Гуттенберг)
- Начальное описание расширения.