XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

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

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

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

783

Revision

1

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

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

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

XR_EXT_spatial_entity

Авторы

Дэниел Гуттенберг (Daniel Guttenberg), Qualcomm
Нихав Джайн (Nihav Jain), Google
Джаред Финдер (Jared Finder), Google
Чжипэн Лю (Zhipeng Liu), ByteDance

Обзор

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

Отслеживаемое изображение представлено как пространственный объект со следующими компонентами:

• XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Обычно приложения используют расширение для отслеживания пространственных изображений следующим образом:

• Сначала приложение создает один или несколько дескрипторов XrSpatialImageTrackingDatabaseEXT на основе наборов предварительно загруженных данных референсных изображений.
• Затем приложение создает дескриптор XrSpatialContextEXT на основе дескрипторов XrSpatialImageTrackingDatabaseEXT, созданных ранее.
• Затем приложение освобождает данные референсного изображения, чтобы уменьшить потребление памяти.
• Приложение обнаруживает и запрашивает изображения в соответствии с шаблонами доступа к пространственным объектам.
• Приложение может загружать дополнительные наборы референсных изображений и создавать на их основе дополнительные XrSpatialImageTrackingDatabaseEXT, а затем XrSpatialContextEXT, чтобы динамически расширять набор обнаруживаемых и отслеживаемых изображений во время выполнения.
• Приложение может уничтожать дескрипторы XrSpatialImageTrackingDatabaseEXT, чтобы динамически сокращать набор обнаруживаемых и отслеживаемых изображений во время выполнения.
• Приложение может уничтожать дескрипторы XrSpatialContextEXT, чтобы динамически сокращать набор обнаруживаемых и отслеживаемых изображений во время выполнения.

Поддержка среды выполнения

Среда выполнения должна объявлять о поддержке функции отслеживания изображений с помощью xrEnumerateSpatialCapabilitiesEXT, указывая следующую возможность:

• XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Конфигурация

Чтобы включить обнаружение и отслеживание плоских изображений, приложение может передавать структуры XrSpatialCapabilityConfigurationImageTrackingEXT в XrSpatialContextCreateInfoEXT :: capabilityConfigs при вызове функции xrCreateSpatialContextAsyncEXT и передавать массивы структур XrSpatialImageTrackingDatabaseEXT в каждой XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Создание набора входных изображений

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

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

Дескриптор XrSpatialImageTrackingDatabaseEXT представляет ресурсы для обнаружения и обновления некоторого количества пространственных изображений в среде пользователя. Приложения могут использовать этот дескриптор для обнаружения и обновления пространственных изображений с помощью других функций в этом расширении.

Создание базы данных для отслеживания пространственных изображений

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

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

• session – это XrSession, в котором будет активна база данных отслеживания пространственных изображений.
• createInfo – это XrSpatialImageTrackingDatabaseCreateInfoEXT, используемый для указания параметров базы данных отслеживания пространственных изображений.
• future – указатель на XrFutureEXT .

Приложение может создать дескриптор XrSpatialImageTrackingDatabaseEXT с помощью функции xrCreateSpatialImageTrackingDatabaseAsyncEXT и настроить наборы входных референсных изображений для базы данных отслеживания изображений с помощью createInfo .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT, если XrSpatialReferenceImageEXT :: format любого из входных референсных изображений не перечислено в xrEnumerateSpatialReferenceImageFormatsEXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_IMAGE_INVALID_EXT, если массив planes в XrSpatialReferenceImageEXT для любого из входных референсных изображений не может быть оценен в соответствии с метаданными референсного изображения XrSpatialReferenceImageEXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_IMAGE_INVALID_EXT, если массив XrSpatialReferenceImageEXT :: planes любого из входных референсных изображений не предоставляет ровно столько же плоскостей, сколько цветовых каналов у XrSpatialReferenceImageEXT :: format.

Если среда выполнения использует систему разрешений для управления доступом приложения к функции отслеживания изображений, то среда выполнения должна возвращать XR_ERROR_PERMISSION_INSUFFICIENT, если эти разрешения не были предоставлены приложению.

Эта функция запускает асинхронную операцию и создает соответствующий объект XrFutureEXT , который можно использовать с xrPollFutureEXT и связанными функциями. Возвращаемое значение этой функции указывает только на то, были ли параметры приемлемыми для планирования асинхронной операции. Соответствующая функция завершения – xrCreateSpatialImageTrackingDatabaseCompleteEXT. Ее можно использовать, когда объект Future из этой функции находится в состоянии READY, а выходные данные заполняются этой функцией в структуре завершения XrCreateSpatialImageTrackingDatabaseCompletionEXT.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до вызова xrCreateSpatialImageTrackingDatabaseAsyncEXT.
• session должен быть действительным дескриптором XrSession.
• createInfo должен быть указателем на действительную структуру XrSpatialImageTrackingDatabaseCreateInfoEXT.
• future должен быть указателем на значение XrFutureEXT.

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

Выполнено

• 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_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
• XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
• XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• spatialReferenceImageCount – количество элементов в массиве spatialReferenceImages.
• spatialReferenceImages – это массив XrSpatialReferenceImageEXT .

Структура XrSpatialImageTrackingDatabaseCreateInfoEXT описывает информацию, необходимую для создания дескриптора XrSpatialImageTrackingDatabaseEXT.

Каждая база данных XrSpatialImageTrackingDatabaseEXT должна быть создана по крайней мере с одним объектом XrSpatialReferenceImageEXT в массиве XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialImageTrackingDatabaseCreateInfoEXT.
• type должно быть XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур . См. также: XrSpatialImageSizeEXT , XrSpatialImageStaticOptimizationEXT.
• spatialReferenceImages должен быть указателем на массив из spatialReferenceImageCount действительных структур XrSpatialReferenceImageEXT.
• Значение параметра spatialReferenceImageCount должно быть больше 0.

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

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

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

• session – это XrSession, ранее переданный в xrCreateSpatialContextAsyncEXT :: session .
• future – это XrFutureEXT, полученный от xrCreateSpatialContextAsyncEXT .
• completion – указатель на XrCreateSpatialImageTrackingDatabaseCompletionEXT .

xrCreateSpatialImageTrackingDatabaseCompleteEXT завершает асинхронную операцию, запущенную xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Среда выполнения не должна обращаться к указателям XrSpatialReferenceImagePlaneEXT :: buffer, предоставленным входным массивом XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages для этого вызова xrCreateSpatialImageTrackingDatabaseAsyncEXT, после его завершения. Чтобы уменьшить объем потребляемой памяти, приложение может освободить любые данные XrSpatialReferenceImagePlaneEXT :: buffer после завершения xrCreateSpatialImageTrackingDatabaseAsyncEXT.

Среда выполнения должна возвращать XR_ERROR_FUTURE_PENDING_EXT, если future не находится в состоянии готовности. Среда выполнения должна возвращать XR_ERROR_FUTURE_INVALID_EXT, если future уже завершено или отменено.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до вызова xrCreateSpatialImageTrackingDatabaseCompleteEXT.
• session должен быть действительным дескриптором XrSession.
• completion должен быть указателем на структуру XrCreateSpatialImageTrackingDatabaseCompletionEXT.

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

Выполнено

• 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

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

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• futureResult – это XrResult операции по созданию базы данных для отслеживания пространственных изображений.
• database – это XrSpatialImageTrackingDatabaseEXT, созданный с использованием данных и конфигурации в xrCreateSpatialImageTrackingDatabaseAsyncEXT :: createInfo .

Коды возврата в будущем

Значения в поле "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_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
• XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Если futureResult – код успешного выполнения, то database должен быть действительным дескриптором. Если database является действительным, он остается таковым только в течение жизненного цикла xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session или до тех пор, пока приложение не уничтожит database с помощью xrDestroySpatialImageTrackingDatabaseEXT (в зависимости от того, что произойдет раньше).

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrCreateSpatialImageTrackingDatabaseCompletionEXT.
• type должно быть XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• futureResult должно быть действительным значением XrResult.
• database должен быть действительным дескриптором XrSpatialImageTrackingDatabaseEXT.

Удалить базу данных отслеживания пространственных изображений

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

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

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

• database – это XrSpatialImageTrackingDatabaseEXT, ранее созданный с помощью xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Приложение может вызвать функцию xrDestroySpatialImageTrackingDatabaseEXT, чтобы освободить дескриптор database и базовые ресурсы после завершения задач по обнаружению и обновлению пространственных изображений.

Приложение может вызвать функцию xrDestroySpatialImageTrackingDatabaseEXT перед вызовом xrDestroySpatialContextEXT . Среда выполнения не должна больше сообщать об изображениях, управляемых этой уничтоженной базой данных XrSpatialImageTrackingDatabaseEXT . Среда выполнения должна продолжать сообщать об образах, управляемых другими базами данных.

Среда выполнения должна гарантировать, что снимки, возвращаемые xrCreateSpatialDiscoverySnapshotCompleteEXT, не содержат изображений, относящихся к уничтоженным или иным образом недействительным дескрипторам XrSpatialImageTrackingDatabaseEXT, даже если дескриптор был уничтожен после того, как приложение вызвало xrCreateSpatialDiscoverySnapshotAsyncEXT . Поскольку данные в пространственном снимке неизменяемы, приложение должно уничтожить все дескрипторы XrSpatialSnapshotEXT, созданные до уничтожения database. В противном случае при использовании xrQuerySpatialComponentDataEXT приложение может получить недействительные дескрипторы XrSpatialImageTrackingDatabaseEXT.

Приложение может вызвать функцию xrDestroySpatialContextEXT, чтобы освободить дескриптор XrSpatialContextEXT, прежде чем уничтожать дескрипторы XrSpatialImageTrackingDatabaseEXT, с которыми был создан XrSpatialContextEXT. Среда выполнения не должна неявно уничтожать эти дескрипторы XrSpatialImageTrackingDatabaseEXT при уничтожении XrSpatialContextEXT.

Независимое управление временем жизни XrSpatialContextEXT и XrSpatialImageTrackingDatabaseEXT позволяет приложениям повторно использовать ранее созданные дескрипторы XrSpatialImageTrackingDatabaseEXT без необходимости повторного выполнения дорогостоящей процедуры создания.

Например, если удалить XrSpatialContextEXT, а затем создать другой XrSpatialContextEXT с той же XrSpatialImageTrackingDatabaseEXT, можно будет приостанавливать и возобновлять отслеживание изображений без повторной инициализации.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до вызова xrDestroySpatialImageTrackingDatabaseEXT.
• database должен быть действительным дескриптором XrSpatialImageTrackingDatabaseEXT.

Потокобезопасность

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

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

Выполнено

• XR_SUCCESS

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

Поддерживаемые форматы входных изображений

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

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

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

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

• instance – дескриптор XrInstance .
• systemId – это XrSystemId, для которого будут перечислены форматы входных референсных изображений.
• capability – это XrSpatialCapabilityEXT, для которого будут перечислены форматы входных референсных изображений.
• formatCapacityInput – емкость массива formats или 0, если нужно получить требуемую емкость.
• formatCountOutput – количество форматов или требуемая емкость, если formatCapacityInput недостаточно.
• formats – массив XrSpatialReferenceImageFormatEXT . Может быть NULL, если formatCapacityInput равно 0.
• Подробное описание того, как получить нужный размер formats, приведено в разделе Параметры размера буфера.

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

Среда выполнения не должна перечислять форматы расширений, которые не включены для instance .

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до вызова xrEnumerateSpatialReferenceImageFormatsEXT.
• instance должен быть действительным дескриптором XrInstance.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• formatCountOutput должен быть указателем на значение uint32_t.
• Если formatCapacityInput не равно 0 , formats должен быть указателем на массив значений formatCapacityInput XrSpatialReferenceImageFormatEXT.

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

Выполнено

• XR_SUCCESS

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_VALIDATION_FAILURE

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

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

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

Необходимо поддерживать как минимум значения XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT и XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT.

Перечисленные значения имеют следующий смысл:

Описания перечислений

• XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT – буфер RGBA. Формат не гарантирует определенное расположение данных пикселей в памяти. Доступ к пикселям должен осуществляться с помощью метаданных, предоставляемых соответствующими структурами XrSpatialReferenceImagePlaneEXT. Каждый цветовой канал пикселя имеет размер 8 бит, поэтому размер каждого пикселя составляет 32 бита.
• XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT – буфер RGB. Формат не гарантирует определенное расположение данных пикселей в памяти. Доступ к пикселям должен осуществляться с помощью метаданных, предоставляемых соответствующими структурами XrSpatialReferenceImagePlaneEXT. Каждый цветовой канал пикселя имеет размер 8 бит, поэтому размер каждого пикселя составляет 24 бита.
• XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT – буфер YUV с субдискретизацией 4:2:0. Формат не гарантирует определенное расположение данных пикселей в памяти. Доступ к пикселям должен осуществляться с помощью метаданных, предоставляемых соответствующими структурами XrSpatialReferenceImagePlaneEXT. Каждый декодированный цветовой канал RGB имеет размер 8 бит, поэтому размер каждого пикселя составляет 24 бита.

Настройки отслеживания пространственных изображений

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

Оптимизация статических изображений

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

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• optimizeForStaticImage – это XrBool32, указывающий, движутся ли изображения. Значение XR_TRUE указывает на то, что изображения не двигаются.

Если XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT перечисляется функцией xrEnumerateSpatialCapabilityFeaturesEXT для возможности XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, приложение может связать XrSpatialImageStaticOptimizationEXT с цепочкой XrSpatialImageTrackingDatabaseCreateInfoEXT :: next или XrSpatialReferenceImageEXT :: next .

Если приложение связывает XrSpatialImageStaticOptimizationEXT со структурой XrSpatialImageTrackingDatabaseCreateInfoEXT, среда выполнения должна считать, что все изображения этой XrSpatialImageTrackingDatabaseEXT являются статическими, если для optimizeForStaticImage задано значение XR_TRUE . Соответственно, среда выполнения должна считать, что все изображения в этой базе данных XrSpatialImageTrackingDatabaseEXT не являются статичными, если для optimizeForStaticImage задано значение XR_FALSE .

Если приложение связывает XrSpatialImageStaticOptimizationEXT со структурой XrSpatialReferenceImageEXT, среда выполнения должна считать, что это референсное изображение статично, если для optimizeForStaticImage задано значение XR_TRUE . Соответственно, среда выполнения должна предполагать, что это референсное изображение не является статичным, если для optimizeForStaticImage задано значение XR_FALSE . Привязка структуры XrSpatialImageStaticOptimizationEXT к структуре XrSpatialReferenceImageEXT имеет приоритет над привязкой к структуре XrSpatialImageTrackingDatabaseCreateInfoEXT.

Если XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT не перечисляется xrEnumerateSpatialCapabilityFeaturesEXT для возможности XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT и приложение связывает структуру XrSpatialImageStaticOptimizationEXT с любой из применимых следующих цепочек, среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Это может помочь среде выполнения точнее определить позу и размер.

Это может снизить энергопотребление.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialImageStaticOptimizationEXT.
• type должно быть XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

Ширина референсного изображения

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

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• physicalWidth – значение float, представляющее физическую ширину в метрах.

Если XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT перечисляется функцией xrEnumerateSpatialCapabilityFeaturesEXT для возможности XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, приложение может связать XrSpatialImageSizeEXT с XrSpatialImageTrackingDatabaseCreateInfoEXT :: next или XrSpatialReferenceImageEXT :: next .

Если приложение связывает XrSpatialImageSizeEXT со структурой XrSpatialImageTrackingDatabaseCreateInfoEXT, среда выполнения должна предполагать, что все изображения этой XrSpatialImageTrackingDatabaseEXT имеют ширину physicalWidth метров и высоту в соответствии с соотношением сторон, неявно заданным через XrSpatialReferenceImageEXT :: width и XrSpatialReferenceImageEXT :: height .

Если приложение связывает XrSpatialImageSizeEXT со структурой XrSpatialReferenceImageEXT, среда выполнения должна предполагать, что ширина этого референсного изображения составляет physicalWidth м, а высота соответствует соотношению сторон, неявно заданному через XrSpatialReferenceImageEXT :: width и XrSpatialReferenceImageEXT :: height . Привязка структуры XrSpatialImageSizeEXT к структуре XrSpatialReferenceImageEXT имеет приоритет над привязкой к структуре XrSpatialImageTrackingDatabaseCreateInfoEXT.

Это может позволить среде выполнения возвращать более точные позу и размер.

Среда выполнения должна перечислять XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT, XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT или оба этих значения.

Если XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT перечисляется с помощью xrEnumerateSpatialCapabilityFeaturesEXT, среда выполнения должна автоматически предоставлять размеры изображений, для которых приложение не предоставило структуры XrSpatialImageSizeEXT в рамках любой из применимых следующих цепочек.

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

Если XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT не перечислено в xrEnumerateSpatialCapabilityFeaturesEXT, приложение должно связать структуры XrSpatialImageSizeEXT с соответствующими следующими цепочками, чтобы для всех изображений был явно указан размер. В противном случае среда выполнения должна вернуть XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT из xrCreateSpatialImageTrackingDatabaseAsyncEXT.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialImageSizeEXT.
• type должно быть XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

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

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• capability – это XrSpatialCapabilityEXT, и его значение должно быть XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
• enabledComponentCount – uint32_t, указывающее количество элементов в enabledComponents .
• enabledComponents – массив XrSpatialComponentTypeEXT, который указывает, какие компоненты нужно включить для этой функции.
• imageTrackingDatabaseCount – unint32_t, указывающее количество элементов в imageTrackingDatabases .
• imageTrackingDatabases – массив дескрипторов XrSpatialImageTrackingDatabaseEXT, который указывает, какие базы данных для отслеживания изображений нужно включить для пространственного контекста.

Если отслеживание изображений поддерживается, среда выполнения должна включить его, когда структура XrSpatialCapabilityConfigurationImageTrackingEXT передается в XrSpatialContextCreateInfoEXT :: capabilityConfigs при вызове xrCreateSpatialContextAsyncEXT .

Структура XrSpatialCapabilityConfigurationImageTrackingEXT позволяет приложению обнаруживать референсные изображения, представленные дескрипторами XrSpatialImageTrackingDatabaseEXT в imageTrackingDatabases .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, если XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT не перечислено в xrEnumerateSpatialCapabilitiesEXT .

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialCapabilityConfigurationImageTrackingEXT.
• type должно быть XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• enabledComponents должен быть указателем на массив из enabledComponentCount допустимых значений XrSpatialComponentTypeEXT.
• imageTrackingDatabases должен быть указателем на массив из imageTrackingDatabaseCount действительных дескрипторов XrSpatialImageTrackingDatabaseEXT.
• Значение параметра enabledComponentCount должно быть больше 0.
• Значение параметра imageTrackingDatabaseCount должно быть больше 0.

Пространственное референсное изображение

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

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

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

• bufferSize – размер массива buffer.
• buffer – это массив данных uint8_t, представляющий данные плоскости.
• rowStride – расстояние в байтах между двумя начальными позициями последовательных строк данных пикселей.
• pixelStride – расстояние в байтах между двумя последовательными пикселями.

Среда выполнения должна обращаться к buffer в соответствии с шаблонами, заданными параметрами rowStride и pixelStride.

Приложение должно задать rowStride и pixelStride так, чтобы среда выполнения извлекала только значимые пиксели этого XrSpatialReferenceImagePlaneEXT.

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialReferenceImagePlaneEXT.
• buffer должен быть указателем на массив значений bufferSize uint8_t.
• Значение параметра bufferSize должно быть больше 0.

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

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• width – ширина референсного изображения в пикселях.
• height – высота референсного изображения в пикселях.
• format – это XrSpatialReferenceImageFormatEXT, представляющий формат изображения.
• planeCount – количество элементов в массиве planes.
• planes – массив структур XrSpatialReferenceImagePlaneEXT, представляющих плоскости данных изображения.

Приложение может создать одну или несколько структур XrSpatialReferenceImageEXT, каждая из которых представляет одно входное референсное изображение, передаваемое в функцию xrCreateSpatialImageTrackingDatabaseAsyncEXT через XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages при создании дескриптора XrSpatialImageTrackingDatabaseEXT.

Данные XrSpatialReferenceImagePlaneEXT :: buffer должны предоставляться приложением в порядке слева направо и сверху вниз.

Приложение должно предоставлять структуру XrSpatialReferenceImagePlaneEXT в массиве XrSpatialReferenceImageEXT :: planes для каждого цветового канала XrSpatialReferenceImageEXT :: format .

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialReferenceImageEXT.
• type должно быть XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур . См. также: XrSpatialAnnotationQuadReferenceANDROID , XrSpatialImageSizeEXT , XrSpatialImageStaticOptimizationEXT.
• format должно быть допустимым значением XrSpatialReferenceImageFormatEXT.
• planes должен быть указателем на массив из planeCount действительных структур XrSpatialReferenceImagePlaneEXT.
• Значение параметра planeCount должно быть больше 0.

Гарантированные компоненты

Среда выполнения, поддерживающая XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, должна предоставлять следующие пространственные компоненты в качестве гарантированных компонентов всех объектов, обнаруженных этими возможностями, и должна перечислять их в xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Компонент "2D-изображение"

Структура списка компонентов для запроса данных

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

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• imageCount – количество элементов в массиве images.
• images – это массив XrSpatialImage2DDataEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT, если XrSpatialComponentImage2DListEXT находится в цепочке XrSpatialComponentDataQueryResultEXT :: next, но XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT не включен в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если imageCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialComponentImage2DListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• images должен быть указателем на массив структур imageCount XrSpatialImage2DDataEXT.
• Значение параметра imageCount должно быть больше 0.

Данные компонента

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

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

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

• imageTrackingDatabase – это XrSpatialImageTrackingDatabaseEXT, который обнаружил или отследил изображение.
• referenceImageIndex – индекс, который сопоставляется с массивом входных референсных изображений spatialReferenceImages, с помощью которых был создан imageTrackingDatabase, в XrSpatialImageTrackingDatabaseCreateInfoEXT.

Приложение может использовать imageTrackingDatabase, чтобы определить, какая из ранее созданных баз данных XrSpatialImageTrackingDatabaseEXT содержит референсное изображение этой структуры XrSpatialImage2DDataEXT. Для этой базы данных XrSpatialImageTrackingDatabaseEXT приложение может использовать referenceImageIndex, чтобы идентифицировать XrSpatialReferenceImageEXT этой структуры XrSpatialImage2DDataEXT, сопоставив ее с порядком ввода массива XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

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

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

• Расширение XR_EXT_spatial_image_tracking должно быть включено до использования XrSpatialImage2DDataEXT.
• imageTrackingDatabase должен быть действительным дескриптором XrSpatialImageTrackingDatabaseEXT.

Конфигурация

Если XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT перечислено в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной возможности, приложение может включить ее, добавив значение перечисления в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Этот компонент не требует специальной настройки для включения в следующую цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT .

Ограниченный двухмерный компонент

Ограниченный 2D-компонент предоставляет центр и границы пространственного изображения, представленного объектом, на котором он находится. Подробнее о компоненте Bounded 2D…

Пример кода

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

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

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

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

• XrSpatialImageTrackingDatabaseEXT

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

• xrCreateSpatialImageTrackingDatabaseAsyncEXT
• xrCreateSpatialImageTrackingDatabaseCompleteEXT
• xrDestroySpatialImageTrackingDatabaseEXT
• xrEnumerateSpatialReferenceImageFormatsEXT

Новые структуры

• XrCreateSpatialImageTrackingDatabaseCompletionEXT
• XrSpatialCapabilityConfigurationImageTrackingEXT
• XrSpatialImage2DDataEXT
• XrSpatialImageTrackingDatabaseCreateInfoEXT
• XrSpatialReferenceImageEXT
• XrSpatialReferenceImagePlaneEXT

• Расширение XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentImage2DListEXT

• Расширение XrSpatialReferenceImageEXT , XrSpatialImageTrackingDatabaseCreateInfoEXT :

  • XrSpatialImageSizeEXT
  • XrSpatialImageStaticOptimizationEXT

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

• XrSpatialReferenceImageFormatEXT

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

• XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_image_tracking_SPEC_VERSION

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

  • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

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

  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

• Расширение XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

• Расширение XrSpatialCapabilityFeatureEXT :

  • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
  • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
  • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

• Расширение XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

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

  • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
  • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
  • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
  • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
  • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
  • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Проблемы

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

• Версия 1, 22 апреля 2025 г. (Дэниел Гуттенберг, Qualcomm)

  • Описание расширения