XR_ANDROID_spatial_annotation_tracking

Name String

XR_ANDROID_spatial_annotation_tracking

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

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

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

795

Revision

1

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

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

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

XR_EXT_spatial_entity
и
XR_EXT_spatial_image_tracking

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

2026-01-12

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

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

Авторы

Левана Чен (Levana Chen), Google
Кристофер Фейл (Christopher Feil), Google
Мартин Зундермайер (Martin Sundermeyer), Google
Дэвид Джозеф Тан (David Joseph Tan), Google
Джаред Финдер (Jared Finder), Google
Нихав Джайн (Nihav Jain), Google

Обзор

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

Это расширение предоставляет базовый тип аннотации Quad – многоугольник, у которого ровно четыре стороны, то есть выпуклый четырехугольник, представляющий собой обобщенную двумерную граничную рамку в ссылке среды выполнения. Отслеживаемая аннотация четырехугольника представлена как пространственный объект со следующими компонентами:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Приложения, как правило, могут использовать расширение для отслеживания пространственных аннотаций в следующих случаях:

• Сначала приложение создает дескриптор XrSpatialReferenceCacheANDROID, который начинает записывать ссылки среды выполнения из заданного источника.
• Затем приложение захватывает ссылку на среду выполнения XrSpatialReferenceImageEXT и определяет нужную аннотацию в ссылке в течение времени существования кеша ссылок.
• Затем приложение создает дескриптор XrSpatialContextEXT на основе XrSpatialReferenceImageEXT, предоставленного XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
• Приложение может уничтожить дескриптор XrSpatialReferenceCacheANDROID, чтобы остановить запись ссылок среды выполнения и уменьшить использование памяти, или дождаться события XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID, чтобы подтвердить результат инициализации.
• Затем приложение запрашивает событие XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID, чтобы подтвердить результат инициализации аннотации.
• Если инициализация прошла успешно, приложение может запросить событие XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT, чтобы отслеживать аннотацию.
• Если инициализация не удалась, приложение может использовать код ошибки, возвращенный в событии, чтобы определить причину сбоя, и удалить существующий дескриптор XrSpatialContextEXT, чтобы начать новую аннотацию.
• Независимо от результата инициализации приложение может освободить буфер изображений, чтобы сократить использование памяти после получения события.
• Приложение обнаруживает и запрашивает аннотации в соответствии с шаблонами доступа к пространственным объектам.
• Приложение может создать дополнительный дескриптор XrSpatialContextEXT, чтобы отслеживать аннотации в новой ссылке, пока действует XrSpatialReferenceCacheANDROID .
• Приложение может уничтожать дескрипторы XrSpatialContextEXT, чтобы динамически сокращать набор обнаруживаемых и отслеживаемых аннотаций во время выполнения.

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

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

• XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Если среда выполнения поддерживает отслеживание аннотаций:

• Оно должно поддерживать хотя бы один компонент аннотации, перечислив поддерживаемые компоненты аннотации через xrEnumerateSpatialCapabilityComponentTypesEXT .
• Оно должно поддерживать хотя бы один из форматов XrSpatialReferenceImageFormatEXT, перечисляя поддерживаемые форматы через xrEnumerateSpatialReferenceImageFormatsEXT с параметром capability, заданным как XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• Оно должно поддерживать хотя бы один из источников XrSpatialAnnotationReferenceSourceANDROID, перечисляя поддерживаемые источники через xrEnumerateSpatialAnnotationReferenceSourcesANDROID с параметром capability, установленным на XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

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

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

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

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

Приложение может перечислить список источников ссылок, поддерживаемых заданным XrSystemId, с помощью xrEnumerateSpatialAnnotationReferenceSourcesANDROID .

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

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до вызова xrEnumerateSpatialAnnotationReferenceSourcesANDROID.
• instance должен быть действительным дескриптором XrInstance.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• sourceCountOutput должен быть указателем на значение uint32_t.
• Если sourceCapacityInput не равно 0 , sources должен быть указателем на массив значений sourceCapacityInput XrSpatialAnnotationReferenceSourceANDROID.

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

Выполнено

• 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

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

Перечисление XrSpatialAnnotationReferenceSourceANDROID описывает источник ссылки, которая предоставляет метаданные для аннотации.

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

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

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

Референсное изображение – это необрезанное изображение, полученное от API камеры Android, например Image из ImageReader, связанного с CameraDevice в Camera2, или ImageProxy из ImageAnalysis, связанного с CameraX. Обычно это одна из RGB-камер, направленных вперед.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

Референсное изображение – это необрезанное изображение, полученное из Android MediaProjection API, например изображение из ImageReader, связанное с виртуальным дисплеем MediaProjection. Она может включать виртуальный и реальный контент.

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

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• referenceCacheTimespan указывает временной диапазон в секундах для действительного дескриптора XrSpatialReferenceCacheANDROID.
• maxReferencePixelWidth – максимальная ширина края референсных изображений в пикселях.
• maxReferencePixelHeight – максимальная высота края референсных изображений в пикселях.
• maxReferenceCount указывает максимальное количество референсных изображений, которые могут быть выделены одновременно.
• maxAnnotationCount указывает максимальное количество аннотаций, которые можно отслеживать одновременно.

Если среда выполнения поддерживает отслеживание аннотаций, приложение может проверить соответствующие системные свойства, связав структуру XrSystemSpatialAnnotationPropertiesANDROID с XrSystemProperties при вызове xrGetSystemProperties .

Если XrSpatialReferenceImageEXT :: width из XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference превышает maxReferencePixelWidth , среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE при вызове xrCreateSpatialContextAsyncEXT .

Если XrSpatialReferenceImageEXT :: height из XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference превышает maxReferencePixelHeight , среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE при вызове xrCreateSpatialContextAsyncEXT .

Если XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time находится за пределами временного диапазона XrSpatialReferenceCacheANDROID :: cache , среда выполнения должна возвращать XR_ERROR_TIME_INVALID при вызове xrCreateSpatialContextAsyncEXT . Приложение может повторно создать дескриптор XrSpatialContextEXT с новой привязкой в течение периода действия XrSpatialReferenceCacheANDROID .

Если количество выделенных референсных изображений превышает maxReferenceCount , среда выполнения должна возвращать XR_ERROR_LIMIT_REACHED и указывать на сбой инициализации через XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . Приложение может удалить дескриптор XrSpatialContextEXT и повторить попытку после завершения инициализации.

Если количество активных аннотаций превышает maxAnnotationCount , среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE при вызове xrCreateSpatialContextAsyncEXT .

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

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

Кеш ссылок среды выполнения

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

Дескриптор XrSpatialReferenceCacheANDROID представляет собой кеш ссылок среды выполнения, записанных из определенного источника.

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

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

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

Приложение может создать дескриптор XrSpatialReferenceCacheANDROID, вызвав xrCreateSpatialReferenceCacheAsyncANDROID . Среде выполнения может потребоваться некоторое время, чтобы инициализировать сервисы отслеживания. Затем приложение может повторно вызвать xrCreateSpatialReferenceCacheCompleteANDROID, чтобы проверить, завершена ли эта асинхронная операция.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, если XrSpatialReferenceCacheCreateInfoANDROID :: capability не указан в xrEnumerateSpatialCapabilitiesEXT .

Среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED, если XrSpatialReferenceCacheCreateInfoANDROID :: source не указан в xrEnumerateSpatialAnnotationReferenceSourcesANDROID для заданной возможности.

Приложение может создать только один дескриптор для каждого источника с определенной функцией. В противном случае среда выполнения должна возвращать XR_ERROR_LIMIT_REACHED .

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

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

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

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

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• XR_ERROR_FEATURE_UNSUPPORTED
• 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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• capability – это XrSpatialCapabilityEXT, описывающий, для какой возможности создается кеш.
• source – это XrSpatialAnnotationReferenceSourceANDROID, описывающий источник кеша контрольных точек.

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

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до использования XrSpatialReferenceCacheCreateInfoANDROID.
• type должно быть XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• source должно быть допустимым значением XrSpatialAnnotationReferenceSourceANDROID.

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

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

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

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

Приложение может вызвать xrCreateSpatialReferenceCacheCompleteANDROID, чтобы дождаться завершения асинхронной операции, запущенной xrCreateSpatialReferenceCacheAsyncANDROID .

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

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

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

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

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• XR_ERROR_FEATURE_UNSUPPORTED
• 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

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

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• futureResult – это XrResult операции создания кеша опорных кадров.
• referenceCache – дескриптор XrSpatialReferenceCacheANDROID, если операция выполнена успешно.

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

Значения в поле "futureResult":

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED

Если futureResult – код успешного выполнения, среда выполнения должна вернуть действительный дескриптор referenceCache. Если referenceCache действителен, он остается таковым только в течение времени существования xrCreateSpatialReferenceCacheAsyncANDROID :: session или до тех пор, пока приложение не уничтожит дескриптор с помощью xrDestroySpatialReferenceCacheANDROID, в зависимости от того, что произойдет раньше.

Если referenceCache действителен, он записывает кеши в XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до использования XrCreateSpatialReferenceCacheCompletionANDROID.
• type должно быть XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• futureResult должно быть действительным значением XrResult.
• referenceCache должен быть действительным дескриптором XrSpatialReferenceCacheANDROID.

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

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

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

• cacheHandle – это XrSpatialReferenceCacheANDROID, ранее созданный с помощью xrCreateSpatialReferenceCacheAsyncANDROID .

Приложение может вызвать функцию xrDestroySpatialReferenceCacheANDROID, чтобы освободить дескриптор cacheHandle и базовые ресурсы после создания пространственного контекста.

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до вызова xrDestroySpatialReferenceCacheANDROID.
• cacheHandle должен быть действительным дескриптором XrSpatialReferenceCacheANDROID.

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

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

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

Выполнено

• XR_SUCCESS

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

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

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

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• capability – это XrSpatialCapabilityEXT, и его значение должно быть XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• enabledComponentCount – это uint32_t, описывающий количество элементов в массиве enabledComponents.
• enabledComponents – указатель на массив XrSpatialComponentTypeEXT .
• cache – это XrSpatialReferenceCacheANDROID, ранее созданный для записи ссылок среды выполнения для конфигурации reference.
• time – XrTime, в который регистрируется reference.
• reference – это XrSpatialReferenceImageEXT с аннотациями, связанными с его следующим указателем.

Приложения могут включить пространственную функцию XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, добавив указатель на структуру XrSpatialCapabilityConfigurationAnnotationTrackingANDROID в XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если capability не равно XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, если reference не содержит аннотаций.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, если компонент аннотации указан в enabledComponents, но с reference не связаны соответствующие аннотации.

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если cache не принадлежит тому же XrSession, который передается в xrCreateSpatialContextAsyncEXT .

Среда выполнения должна возвращать XR_ERROR_TIME_INVALID, если time находится за пределами временного диапазона cache .

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до использования XrSpatialCapabilityConfigurationAnnotationTrackingANDROID.
• type должно быть XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• enabledComponents должен быть указателем на массив из enabledComponentCount допустимых значений XrSpatialComponentTypeEXT.
• cache должен быть действительным дескриптором XrSpatialReferenceCacheANDROID.
• reference должно быть действительной структурой XrSpatialReferenceImageEXT.
• Значение параметра enabledComponentCount должно быть больше 0.

События отслеживания аннотаций

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

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• spatialContext – это XrSpatialContextEXT, для которого активировано отслеживание аннотаций.
• annotationIndex сопоставляется с индексом из массива аннотаций, связанного с XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• initializationResult указывает на результат инициализации аннотации. Если это не XR_SUCCESS, приложение может удалить и заново создать дескриптор XrSpatialContextEXT, чтобы повторно инициализировать аннотацию, или продолжить использовать spatialContext для отслеживания других аннотаций.

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

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

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

Среда выполнения должна заполнить initializationResult значением XR_SUCCESS, если аннотация инициализирована успешно. Затем приложение может запросить событие XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT, чтобы отследить аннотацию.

В противном случае среда выполнения должна заполнить initializationResult соответствующим кодом ошибки, чтобы указать причину сбоя. Приложение может удалить дескриптор XrSpatialContextEXT, чтобы начать новую аннотацию, или продолжить использовать spatialContext для отслеживания других аннотаций.

Аннотация Quad

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

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Четырехканальный цифровой отпечаток

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

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• quadCount – это uint32_t, описывающий количество элементов в массиве quads.
• quads – указатель на массив XrSpatialAnnotationQuadANDROID .

Если среда выполнения поддерживает четырехугольные аннотации, приложение может настроить их, связав структуру XrSpatialAnnotationQuadReferenceANDROID с XrSpatialReferenceImageEXT :: next и задав ссылку в XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference при создании дескриптора XrSpatialContextEXT.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT из xrCreateSpatialContextAsyncEXT, если quadCount равно 0.

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до использования XrSpatialAnnotationQuadReferenceANDROID.
• type должно быть XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• quads должен быть указателем на массив из quadCount допустимых структур XrSpatialAnnotationQuadANDROID.
• Значение параметра quadCount должно быть больше 0.

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

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

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

• alignment – XrSpatialAnnotationQuadAlignmentANDROID четырехугольника.
• upperLeft – это XrVector2f, описывающий координату верхнего левого угла четырехугольника, связанного с источником.
• upperRight – это XrVector2f, описывающий координату правого верхнего угла четырехугольника, связанного с началом координат.
• lowerRight – это XrVector2f, описывающий координату правого нижнего угла четырехугольника, связанного с началом координат.
• lowerLeft – это XrVector2f, описывающий координату левого нижнего угла четырехугольника относительно начала координат.

Четырехугольник в двумерном пространстве – это выпуклый четырехугольник, вершины которого расположены по часовой стрелке. Значения четырех углов связаны с началом координат (0, 0), с которым связан четырехугольник.

• Если он связан с XrSpatialReferenceImageEXT, то началом координат будет левый верхний угол изображения, где X соответствует пикселю по ширине, а Y – пикселю по высоте.
• Если он связан с XrSpatialAnnotationQuadDataANDROID , начало координат указывается в XrSpaceLocationData :: pose из XrSpatialAnnotationQuadDataANDROID :: origin .

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до использования XrSpatialAnnotationQuadANDROID.
• alignment должно быть действительным значением XrSpatialAnnotationQuadAlignmentANDROID.

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID = 2,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

Перечисление XrSpatialAnnotationQuadAlignmentANDROID описывает выравнивание четырехугольной аннотации.

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

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID

Четырехугольник аннотации находится в одной плоскости с поверхностью объекта, если отслеживаемая цель – плоский объект или поверхность. Результат идеально соответствует физической геометрии объекта, а его перспектива корректируется так, чтобы он лежал ровно на этой конкретной поверхности.

Компоненты Quad

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

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

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

• annotationIndex – индекс, сопоставленный с массивом XrSpatialAnnotationQuadReferenceANDROID :: quads, который связан с ссылкой, переданной XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• origin – это XrSpaceLocationData, описывающий начало двумерной плоскости, в которой укоренен четырехугольник. Среда выполнения должна задавать XrSpaceLocationData :: locationFlags, чтобы указывать допустимые биты исходного положения.
• quad – это XrSpatialAnnotationQuadANDROID, представляющий четырехугольник в локальном пространстве. Используйте origin, чтобы преобразовать четырехугольник в пространство позы.

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

• Расширение XR_ANDROID_spatial_annotation_tracking должно быть включено до использования XrSpatialAnnotationQuadDataANDROID.
• origin должен быть допустимой структурой XrSpaceLocationData.
• quad должно быть допустимой структурой XrSpatialAnnotationQuadANDROID.

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

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• quadCount – это uint32_t, описывающий количество элементов в массиве quads.
• quads – массив XrSpatialAnnotationQuadDataANDROID .

Приложение может запрашивать компонент аннотации четырехугольника пространственных объектов в XrSpatialSnapshotEXT, добавив XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID в XrSpatialComponentDataQueryConditionEXT :: componentTypes и XrSpatialComponentAnnotationQuadListANDROID в следующую цепочку указателей XrSpatialComponentDataQueryResultEXT .

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

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

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

• Перед использованием XrSpatialComponentAnnotationQuadListANDROID необходимо включить расширение XR_ANDROID_spatial_annotation_tracking.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• quads должен быть указателем на массив структур quadCount XrSpatialAnnotationQuadDataANDROID.
• Значение параметра quadCount должно быть больше 0.

Пример кода

Проверьте поддержку среды выполнения

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

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
                                         &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
                                         &capabilityCount,
                                         capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
              XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

Настроить аннотацию Quad

В следующем примере кода показано, как настроить аннотацию четырехугольника.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

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

  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
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

Как посмотреть активные аннотации

В примере кода ниже показано, как находить аннотации и запрашивать их.

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  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 = baseSpace;
  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 desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    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<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

    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 XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

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

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

  XrSpace space;           // Application's play space.
  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_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    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, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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

• XrSpatialReferenceCacheANDROID

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

• xrCreateSpatialReferenceCacheAsyncANDROID
• xrCreateSpatialReferenceCacheCompleteANDROID
• xrDestroySpatialReferenceCacheANDROID
• xrEnumerateSpatialAnnotationReferenceSourcesANDROID

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

• XrCreateSpatialReferenceCacheCompletionANDROID
• XrEventDataSpatialAnnotationTrackingANDROID
• XrSpatialAnnotationQuadANDROID
• XrSpatialAnnotationQuadDataANDROID
• XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
• XrSpatialReferenceCacheCreateInfoANDROID

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

  • XrSpatialComponentAnnotationQuadListANDROID

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

  • XrSpatialAnnotationQuadReferenceANDROID

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

  • XrSystemSpatialAnnotationPropertiesANDROID

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

• XrSpatialAnnotationQuadAlignmentANDROID
• XrSpatialAnnotationReferenceSourceANDROID

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

• XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
• XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

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

  • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

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

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

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

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

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

  • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
  • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
  • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

Проблемы

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

• Версия 1, 17 сентября 2025 г. (Левана Чен)

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